Integrate Invoicing

DocsCurrentLast updated: April 6th 2022, @ 6:06:12 pm

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.

1. Create draft

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

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

This sample request creates an invoice:

From sender David Larusso, including address, email address, and phone number.
To recipient Stephanie Meyers, including address, email address, and phone number.
For one $50 yoga mat including sales tax.
For one $10 t-shirt including sales tax.
With $20 minimum partial payments enabled.
With an optional tip.
With $10 packing charges and $10 shipping charges including sales tax.
With a 5% invoice discount.

Modify the code

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

Change ACCESS-TOKEN to your access token.
Change BN-CODE to your build notation code.
Change merchant@example.com in invoicer: email_address to the primary_email of the merchant received in GET /v1/customer/partners/{partner_id}/merchant-integrations/{merchant_id} API.
Change 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, make sure the due_date is within the specified term.
Optional: Customize your invoice with other invoice parameters.

Step result

A successful request returns the following:

An invoice in your sandbox business account in Draft status. See this status by logging into your sandbox business account.
A return status code of HTTP 201 Created.
A JSON response body that has an ID of the invoice. In the sample response, the ID is INV2-W44B-KRGF-JM6R-26VU.

Use this ID to complete other REST API actions, such as editing or deleting the invoice and sending payment reminders.

Sample response

1{
2          "rel": "self",
3          "href": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU",
4          "method": "GET"
5      }

2. Send

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

Sample request

API endpoint used: Send invoice

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 -d '{
5        "send_to_invoicer": true
6      }'

Modify code

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

Change ACCESS-TOKEN to your access token.
Change INVOICE-ID to the invoice ID that was 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 with information about the invoice.
The invoice status in the merchant’s PayPal account moves to Unpaid (Sent).
An email is sent, if you set email notifications in the request body.

Tip: PayPal automatically records payments made in the invoice using the Pay Now button. If you accept payments offline, such as a check or a wire transfer, you'll need to manually record the payment.

Sample response

1{
2          "rel": "self",
3          "href": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU",
4          "method": "GET"
5      }

Next steps

Customize your Invoicing integration