Invoicing Basic Integration
APILegacyLast updated: April 6th 2022, @ 6:06:12 pm
This basic integration explains how to create and send an invoice. These are the minimum steps required to integrate invoicing.
Availability: This is Invoicing v2. If you integrated before April 2019, see version 1.
1. Set up your development environment
Before you can integrate Invoicing, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.
Then, return to this page to integrate Invoicing.
2. Create draft invoice
In the JSON request body, use the data values from your order to set the invoice request parameters. The merchant information email must be a confirmed email address on the payment recipient’s PayPal account. This step generates an invoice that you can send in the next step.
This sample request creates a draft invoice:
{
"detail": {
"invoice_number": "#12345",
"reference": "deal-ref",
"currency_code": "USD",
"note": "Thank you for your business.",
"term": "No refunds after 30 days.",
"memo": "This is a long contract",
"payment_term": {
"term_type": "NET_10"
}
},
"invoicer": {
"name": {
"given_name": "David",
"surname": "Larusso"
},
"address": {
"address_line_1": "1234 First Street",
"admin_area_2": "Anytown",
"admin_area_1": "CA",
"postal_code": "98765",
"country_code": "US"
},
"phones": [{
"country_code": "001",
"national_number": "4085551234",
"phone_type": "MOBILE"
}],
"website": "www.test.com",
"tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy- Jb5SeuGj185MNNw6g",
"logo_url": "https://example.com/logo.png",
"additional_notes": "2-4"
},
"primary_recipients": [{
"billing_info": {
"name": {
"given_name": "Stephanie",
"surname": "Meyers"
},
"address": {
"address_line_1": "1234 Main Street",
"admin_area_2": "Anytown",
"admin_area_1": "CA",
"postal_code": "98765",
"country_code": "US"
},
"email_address": "bill-me@example.com",
"phones": [{
"country_code": "001",
"national_number": "4884551234",
"phone_type": "HOME"
}],
"additional_info_value": "add-info"
},
"shipping_info": {
"name": {
"given_name": "Stephanie",
"surname": "Meyers"
},
"address": {
"address_line_1": "1234 Main Street",
"admin_area_2": "Anytown",
"admin_area_1": "CA",
"postal_code": "98765",
"country_code": "US"
}
}
}],
"items": [{
"name": "Yoga Mat",
"description": "Elastic mat to practice yoga.",
"quantity": "1",
"unit_amount": {
"currency_code": "USD",
"value": "50.00"
},
"tax": {
"name": "Sales Tax",
"percent": "7.25"
},
"discount": {
"percent": "5"
},
"unit_of_measure": "QUANTITY"
}, {
"name": "Yoga t-shirt",
"quantity": "1",
"unit_amount": {
"currency_code": "USD",
"value": "10.00"
},
"tax": {
"name": "Sales Tax",
"percent": "7.25"
},
"discount": {
"amount": {
"currency_code": "USD",
"value": "5.00"
}
},
"unit_of_measure": "QUANTITY"
}],
"configuration": {
"partial_payment": {
"allow_partial_payment": true,
"minimum_amount_due": {
"currency_code": "USD",
"value": "20.00"
}
},
"allow_tip": true,
"tax_calculated_after_discount": true,
"tax_inclusive": false
},
"amount": {
"breakdown": {
"custom": {
"label": "Packing Charges",
"amount": {
"currency_code": "USD",
"value": "10.00"
}
},
"shipping": {
"amount": {
"currency_code": "USD",
"value": "10.00"
},
"tax": {
"name": "Sales Tax",
"percent": "7.25"
}
},
"discount": {
"invoice_discount": {
"percent": "5"
}
}
}
}
}
Sample response
A successful request returns the HTTP 201 Created status code and a JSON response body that shows invoice details. Save the id field value.
The links array in the response contains HATEOAS links that enable you to complete other actions for the invoice.
{
"id": "INV2-PXSC-LFZ3-FDAX-HR3E",
"status": "DRAFT",
"detail": {
"reference": "deal-ref",
"currency_code": "USD",
"note": "Thank you for your business.",
"memo": "This is a long contract",
"additional_data": "2-4",
"category_code": "SHIPPABLE",
"invoice_number": "#12345",
"invoice_date": "2020-01-28",
"payment_term": {
"term_type": "NET_10",
"due_date": "2020-02-07"
},
"viewed_by_recipient": false,
"metadata": {
"create_time": "2020-01-28T20:54:48Z",
"last_update_time": "2020-01-28T20:54:48Z",
"created_by_flow": "REGULAR_SINGLE",
"recipient_view_url": "https://www.sandbox.paypal.com/invoice/p/#PXSCLFZ3FDAXHR3E",
"invoicer_view_url": "https://www.sandbox.paypal.com/invoice/details/INV2-PXSC-LFZ3-FDAX-HR3E"
},
"archived": false
},
"invoicer": {
"name": {
"given_name": "David",
"surname": "Larusso",
"full_name": "David Larusso"
},
"address": {
"address_line_1": "1234 First Street",
"admin_area_2": "Anytown",
"admin_area_1": "CA",
"postal_code": "98765",
"country_code": "US"
},
"phones": [{
"country_code": "001",
"national_number": "4085551234",
"phone_type": "MOBILE"
}],
"website": "www.test.com",
"tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy- Jb5SeuGj185MNNw6g",
"additional_notes": "2-4",
"logo_url": "https://example.com/logo.png"
},
"primary_recipients": [{
"billing_info": {
"name": {
"given_name": "Stephanie",
"surname": "Meyers",
"full_name": "Stephanie Meyers"
},
"address": {
"address_line_1": "1234 Main Street",
"admin_area_2": "Anytown",
"admin_area_1": "CA",
"postal_code": "98765",
"country_code": "US"
},
"email_address": "bill-me@example.com"
},
"shipping_info": {
"name": {
"given_name": "Stephanie",
"surname": "Meyers",
"full_name": "Stephanie Meyers"
},
"address": {
"address_line_1": "1234 Main Street",
"admin_area_2": "Anytown",
"admin_area_1": "CA",
"postal_code": "98765",
"country_code": "US"
}
}
}],
"items": [{
"id": "ITEM-97V00660JE381301E",
"name": "Yoga Mat",
"description": "Elastic mat to practice yoga.",
"quantity": "1",
"unit_amount": {
"currency_code": "USD",
"value": "50.00"
},
"tax": {
"id": "TAX-7FC79953CG799523R",
"name": "Sales Tax",
"percent": "7.25",
"amount": {
"currency_code": "USD",
"value": "3.27"
}
},
"discount": {
"percent": "5",
"amount": {
"currency_code": "USD",
"value": "-2.50"
}
},
"unit_of_measure": "QUANTITY"
}, {
"id": "ITEM-9NY92987V15309140",
"name": "Yoga t-shirt",
"quantity": "1",
"unit_amount": {
"currency_code": "USD",
"value": "10.00"
},
"tax": {
"id": "TAX-7FC79953CG799523R",
"name": "Sales Tax",
"percent": "7.25",
"amount": {
"currency_code": "USD",
"value": "0.34"
}
},
"discount": {
"amount": {
"currency_code": "USD",
"value": "-5.00"
}
},
"unit_of_measure": "QUANTITY"
}],
"configuration": {
"tax_calculated_after_discount": true,
"tax_inclusive": false,
"allow_tip": true,
"partial_payment": {
"allow_partial_payment": true,
"minimum_amount_due": {
"currency_code": "USD",
"value": "20.00"
}
},
"template_id": "TEMP-2DD658352B363453P"
},
"amount": {
"breakdown": {
"item_total": {
"currency_code": "USD",
"value": "60.00"
},
"discount": {
"invoice_discount": {
"percent": "5",
"amount": {
"currency_code": "USD",
"value": "-2.63"
}
},
"item_discount": {
"currency_code": "USD",
"value": "-7.50"
}
},
"tax_total": {
"currency_code": "USD",
"value": "4.34"
},
"shipping": {
"amount": {
"currency_code": "USD",
"value": "10.00"
},
"tax": {
"id": "TAX-128425447T036552L",
"name": "Sales Tax",
"percent": "7.25",
"amount": {
"currency_code": "USD",
"value": "0.73"
}
}
},
"custom": {
"label": "Packing Charges",
"amount": {
"currency_code": "USD",
"value": "10.00"
}
}
},
"currency_code": "USD",
"value": "74.21"
},
"due_amount": {
"currency_code": "USD",
"value": "74.21"
},
"links": [{
"href": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-PXSC-LFZ3-FDAX-HR3E",
"rel": "self",
"method": "GET"
}, {
"href": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-PXSC-LFZ3-FDAX-HR3E/send",
"rel": "send",
"method": "POST"
}, {
"href": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-PXSC-LFZ3-FDAX-HR3E",
"rel": "replace",
"method": "PUT"
}, {
"href": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-PXSC-LFZ3-FDAX-HR3E",
"rel": "delete",
"method": "DELETE"
}, {
"href": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-PXSC-LFZ3-FDAX-HR3E/payments",
"rel": "record-payment",
"method": "POST"
}]
}
3. Send invoice
When you send an invoice to your customer, the invoice moves from the draft to the payable state and these actions occur:
- Both you and your customer receive an email notification.
- The invoice status updates to
SENT. - The customer’s view of the invoice includes an online payment button.
To send an invoice, include the invoice id from the create invoice call in the URI of the send request. If the invoice issue date is current or in the past, the invoice sends immediately. If the invoice issue date is in the future, the invoice is scheduled to send on the future date.
To suppress the merchant's email notification, set the send_to_invoicer query parameter to false.
To send the invoice through a share link and not through PayPal, set the send_to_recipient parameter to false in the notification object. The send_to_recipient property does not apply to a future issue date because the invoice is scheduled to be sent through PayPal on that date.
Note: You can send an invoice only once. If you need to make changes, you can send an update and set the
send_to_recipienttotrue. If no changes are required, you can send an invoice reminder.
This sample request sends an invoice to the customer:
curl -v -X POST \
https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/send \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Access-Token>"
A successful request returns the HTTP 200 OK status code with no JSON response body.
Next
When you've completed this basic integration, you can test your work or add more functionality from the Full Integration section.