Invoicing
Create invoices to provide your buyers with an itemized list of goods and services, such as cost, quantity, taxes, discounts, and other fields.
Know before you code
-
Complete Onboarding before you begin this integration.
-
In the
POST /v2/customer/partner-referrals
API:- Pass the
INVOICE_READ_WRITE
andACCESS_MERCHANT_INFORMATION
permissions in thefeatures
object. - Pass products as
EXPRESS_CHECKOUT
- Pass the
- Get the email address returned in the
primary_email
field of theGET /v2/customer/partners/{partner_id}/merchant-integrations/{merchant_id}
API response. You'll use this in the Invoicing APIs.
-
- The instructions in Get started will help you get your access token.
- You'll need your build notation (BN) code. If you don't have it, contact your PayPal sales manager.
- This integration uses the Invoicing REST API.
1. Create draft invoice
To draft an invoice, copy the following code and modify it.
Sample request
API endpoint used: Create draft invoice
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Access-Token>" \
-H "PayPal-Partner-Attribution-Id: <BN-Code>" \
-d '{
"detail": {
"invoice_number": "123",
"reference": "deal-ref",
"invoice_date": "2020-11-12",
"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",
"due_date": "2020-11-22"
}
},
"invoicer": {
"name": {
"given_name": "David",
"surname": "Larusso"
},
"address": {
"address_line_1": "1234 First Street",
"address_line_2": "337673 Hillside Court",
"admin_area_2": "Anytown",
"admin_area_1": "CA",
"postal_code": "98765",
"country_code": "US"
},
"email_address": "<merchant@example.com>",
"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,
"template_id": ""
},
"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"
}
}
}
}
}'
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>
ininvoicer: email_address
to theprimary_email
of the Merchant received inGET /v1/customer/partners/{partner_id}/merchant-integrations/{merchant_id}
API. - Change
invoice_date
anddue_date
to reflect the current or a future date. - Optional: Use the details from your order to set other invoice request parameters to populate the details of the invoice.
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
{
"rel": "self",
"href": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU",
"method": "GET"
}
2. Send invoice
To send the invoice, copy the following code and modify it.
Sample request
API endpoint used: Send invoice
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU /send \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Access-Token>" \
-d '{
"send_to_invoicer": true
}'
Modify the code
After you copy the code in the sample request, modify the following:
- Change
Access-Token
to your access token. - Change the sample invoice ID,
INV2-W44B-KRGF-JM6R-26VU
, to the invoice ID that was returned when you created the invoice. - Optional: If you don't want PayPal to email the invoice notification to your buyer when you create it, because you want to send a QR code, set
send_to_recipient
tofalse
. This parameter updates the invoice status toUNPAID
and does not send the email notification.
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)
. - If you set email notifications in the request body, the emails are sent.
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, manually record the payment.
Sample response
{
"rel": "self",
"href": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU",
"method": "GET"
}
Next steps
See also
- Create QR codes so your buyers can easily view their invoice and pay online
- Use other Invoicing REST API endpoints to manage your invoices, such as record invoice payments, send invoice reminders, and refunds on invoices.