Integrate Invoicing

DocsCurrentLast updated: September 6th 2023, @ 12:43:42 pm

Know before you code

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

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 merchant@example.com in invoicer: email_address to your sandbox business account email address. Make sure the sandbox business account is associated with the access token you use to call the endpoint. When you go live, use the email address associated with your PayPal business account.
Change payer@example.com in primary_recipients: email_address to a sandbox personal account.
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/INVOICE-ID",
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 the 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 changes 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/INVOICE-ID",
4          "method": "GET"
5      }

Next steps

Customize your Invoicing integration