Integrate invoicing

DOCSCURRENT

Last updated: Feb 27th, 1:49pm

Know before you code

This integration is available to select partners only.

Complete Onboarding before you begin this integration.
- In the POST /v2/customer/partner-referrals API:
  - Pass the INVOICE_READ_WRITE and ACCESS_MERCHANT_INFORMATION permissions in the features object.
  - Pass products as EXPRESS_CHECKOUT
- Get the email address returned in the primary_email field of the GET /v2/customer/partners/{partner_id}/merchant-integrations/{merchant_id} API response. You'll use this in the Invoicing APIs.

Complete the steps in Get started to get your credentials.

Use your sandbox business email address as the address for the Invoicer API object.

This integration uses the Invoicing REST API.

You can make test calls to the Invoicing API with the PayPal API Executor.

Use Postman to explore and test PayPal APIs.

Create draft invoice

To draft an invoice, copy the following code and modify it as needed.

API endpoint used: Create draft invoice

Sample request
Sample response

1curl -v -X POST 'https://api-m.sandbox.paypal.com/v2/invoicing/invoices' \
2 -H 'Content-Type: application/json' \
3 -H 'Authorization: Bearer ACCESS-TOKEN' \
4 -H 'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION' \
5 -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
6 -d '{
7          "detail": {
8            "invoice_number": "123",
9            "reference": "deal-ref",
10            "invoice_date": "2028-11-22",
11            "currency_code": "USD",
12            "note": "Thank you for your business.",
13            "term": "No refunds after 30 days.",
14            "memo": "This is a long contract",
15            "payment_term": {
16              "term_type": "DUE_ON_DATE_SPECIFIED",
17              "due_date": "2028-11-22"
18            }
19          },
20          "invoicer": {
21            "name": {
22              "given_name": "David",
23              "surname": "Larusso"
24            },
25            "address": {
26              "address_line_1": "1234 First Street",
27              "address_line_2": "337673 Hillside Court",
28              "admin_area_2": "Anytown",
29              "admin_area_1": "CA",
30              "postal_code": "98765",
31              "country_code": "US"
32            },
33            "email_address": "merchant@example.com",
34            "phones": [
35              {
36                "country_code": "001",
37                "national_number": "4085551234",
38                "phone_type": "MOBILE"
39              }
40            ],
41            "website": "https://example.com",
42            "tax_id": "XX-XXXXXXX",
43            "logo_url": "https://example.com/logo.PNG",
44            "additional_notes": "example note"
45          },
46          "primary_recipients": [
47            {
48              "billing_info": {
49                "name": {
50                  "given_name": "Stephanie",
51                  "surname": "Meyers"
52                },
53                "address": {
54                  "address_line_1": "1234 Main Street",
55                  "admin_area_2": "Anytown",
56                  "admin_area_1": "CA",
57                  "postal_code": "98765",
58                  "country_code": "US"
59                },
60                "email_address": "payer@example.com",
61                "phones": [
62                  {
63                    "country_code": "001",
64                    "national_number": "4884551234",
65                    "phone_type": "HOME"
66                  }
67                ],
68                "additional_info_value": "add-info"
69              },
70              "shipping_info": {
71                "name": {
72                  "given_name": "Stephanie",
73                  "surname": "Meyers"
74                },
75                "address": {
76                  "address_line_1": "1234 Main Street",
77                  "admin_area_2": "Anytown",
78                  "admin_area_1": "CA",
79                  "postal_code": "98765",
80                  "country_code": "US"
81                }
82              }
83            }
84          ],
85          "items": [
86            {
87              "name": "Yoga mat",
88              "description": "Elastic mat to practice yoga.",
89              "quantity": "1",
90              "unit_amount": {
91                "currency_code": "USD",
92                "value": "50.00"
93              },
94              "tax": {
95                "name": "Sales Tax",
96                "percent": "7.25"
97              },
98              "discount": {
99                "percent": "5"
100              },
101              "unit_of_measure": "QUANTITY"
102            },
103            {
104              "name": "Yoga t-shirt",
105              "quantity": "1",
106              "unit_amount": {
107                "currency_code": "USD",
108                "value": "10.00"
109              },
110              "tax": {
111                "name": "Sales Tax",
112                "percent": "7.25"
113              },
114              "discount": {
115                "amount": {
116                  "currency_code": "USD",
117                  "value": "5.00"
118                }
119              },
120              "unit_of_measure": "QUANTITY"
121            }
122          ],
123          "configuration": {
124            "partial_payment": {
125              "allow_partial_payment": true,
126              "minimum_amount_due": {
127                "currency_code": "USD",
128                "value": "20.00"
129              }
130            },
131            "allow_tip": true,
132            "tax_calculated_after_discount": true,
133            "tax_inclusive": false,
134            "template_id": ""
135          },
136          "amount": {
137            "breakdown": {
138              "custom": {
139                "label": "Packing Charges",
140                "amount": {
141                  "currency_code": "USD",
142                  "value": "10.00"
143                }
144              },
145              "shipping": {
146                "amount": {
147                  "currency_code": "USD",
148                  "value": "10.00"
149                },
150                "tax": {
151                  "name": "Sales Tax",
152                  "percent": "7.25"
153                }
154              },
155              "discount": {
156                "invoice_discount": {
157                  "percent": "5"
158                }
159              }
160            }
161          }
162        }'

This sample request demonstrates how to create an invoice:

From: Sender David Larusso, including their address, email address, and phone number.

To: Recipient Stephanie Meyers, including their address, email address, and phone number.

Items:

One yoga mat priced at $50, including sales tax.

One t-shirt priced at $10, including sales tax.

Partial Payments: Enabled with a $20 minimum.

Optional Tip: Allowed.

Additional Charges:

$10 packing charges, including sales tax.

$10 shipping charges, including sales tax.

Discount: A 5% invoice discount applied.

Modify the code

After you copy the code in the sample request, modify the following:

Replace ACCESS-TOKEN with your access token.

Replace PAYPAL-AUTH-ASSERTION with your PayPal-Auth-Assertion token.

Replace BN-CODE with your PayPal Attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.

Replace merchant@example.com in invoicer: email_address to the primary_email of the merchant retrieved from GET /v1/customer/partners/{partner_id}/merchant-integrations/{merchant_id} API.

Update invoice_date and due_date to reflect the current or a future date in the format YYYY-MM-DD. If you set a term_type, ensure the due_date falls within the specified term.

Optional: Customize your invoice with additional invoice parameters as needed.

Step result

A successful request returns the following:

An invoice in your sandbox business account with the status set to Draft. You can view this status by logging into your sandbox business account.

A return status code of HTTP 201 Created.

A JSON response body that includes the ID of the invoice. In the sample response, the ID is INV2-W44B-KRGF-JM6R-26VU.

You can use this ID to perform other REST API actions, such as editing or deleting the invoice or sending payment reminders.

Send

To send the invoice, copy the following code and modify it as needed.

API endpoint used: Send invoice

Sample request
Sample response

1curl -v -X POST 'https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INVOICE-ID/send' \
2 -H 'Content-Type: application/json' \
3 -H 'Authorization: Bearer ACCESS-TOKEN' \
4 -H 'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION' \
5 -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
6 -d '{
7        "send_to_invoicer": true
8      }'

Modify the code

After you copy the code in the sample request, modify the following:

Replace ACCESS-TOKEN with your access token.

Replace PAYPAL-AUTH-ASSERTION with your PayPal-Auth-Assertion token.

Replace BN-CODE with your PayPal Attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.

Replace INVOICE-ID to the invoice ID returned when you created the invoice.

Step result

A successful request returns the following:

A return status code of HTTP 200 OK.

A JSON response body containing information about the invoice.

The invoice status in the merchant’s PayPal account changes to Unpaid (Sent).

An email is sent, if you set email notifications in the request body.

Tip: PayPal automatically records payments made through the invoice's Pay Now button. If you accept payments offline, such as by check or wire transfer, you will need to manually record the payment.

Next steps

Customize your Invoicing integration