Invoices(2)

API Version v2

?This API is currently not supported by our SDK

Use the Invoicing API to create, send, and manage invoices. You can also use the API or webhooks to track invoice payments. When you send an invoice to a customer, the invoice moves from draft to payable state. PayPal then emails the customer a link to the invoice on the PayPal website. Customers with a PayPal account can log in and pay the invoice with PayPal. Alternatively, customers can pay as a guest with a debit card or credit card. For more information, see the Invoicing Overview and the Invoicing Integration Guide.

operation/invoices.create Create draft invoice

post/v2/invoicing/invoices

Try it

Creates a draft invoice. To move the invoice from a draft to payable state, you must send the invoice.

In the JSON request body, include invoice details including merchant information. The invoice object must include an items array.

Note: The merchant that you specify in an invoice must have a PayPal account in good standing.

SecurityOauth2

Request

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json required

The invoice details which includes all information of the invoice like items, billing information.


primary_recipients	Array of objects (recipient_info) [ 0 .. 100 ] items The billing and shipping information. Includes name, email, address, phone and language.
additional_recipients	Array of strings<ppaas_common_email_address_v2> (email_address) [ 0 .. 100 ] items An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice. > Note: Valid values are email addresses in the `additional_recipients` value associated with the invoice.
items	Array of objects (item) [ 0 .. 100 ] items An array of invoice line item information.
detail required	object (invoice_detail) The details of the invoice. Includes invoice number, date, payment terms, and audit metadata.
invoicer	object (invoicer_info) The invoicer business information that appears on the invoice.
configuration	object (configuration) The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
amount	object (amount_summary_detail) The invoice amount summary of item total, discount, tax total, and shipping.
settings	object (invoice_settings) The settings for the invoice.
payments	object (payments) An array of payments registered against the invoice.
effective_invoice_total	object (Money) The effective total amount of the invoice after applying conditional rules. The conditional rules include early payment discount, late payment surcharge, and auto cancellation details.
effective_due_amount	object (Money) The effective due amount of the invoice after applying conditional rules. The conditional rules include early payment discount, late payment surcharge, and auto cancellation details.
refunds	object (refunds) The invoicing refund details. Includes the refund type, date, amount, and method.

Responses

201 A successful request returns the HTTP 201 Created status code. A JSON response body that shows invoice details is returned if you set prefer=return=representation.

Request samples

Payload
cURL
Node.js
Java
Python

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Sample 1 - 201 - Create Invoice with ThemeSample 1 - 201 - Create Invoice with Theme

Copy

Expand allCollapse all

`{"detail": {"reference": "deal-ref",

"invoice_date": "2025-01-15",

"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": "2025-01-25"

"order_details": "Order #12345 placed on January 10, 2025.",

"project_details": "Website redesign project for client XYZ Corp.",

"service_details": "Consulting services provided from Jan-Mar 2025.",

"cancellation_policy": "Services may be cancelled with 14-day notice.",

"payment_terms": "Payment due within 10 days of invoice date.",

"return_policy": "All sales are final. No returns accepted after 30 days.",

"service_agreement": "Services provided as per agreement dated Jan 1, 2025.",

"tip_presets": [{"percent": "15"

},

{"percent": "20"

},

{"percent": "25"

}

]

"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",

"tax_note": "Reduced tax rate"

},

"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,

"show_additional_item_fields": true,

"template_id": "TEMP-19V05281TU309413B",

"theme": {"primary_color": "#4A90D9"

}

"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"

}

"settings": {"invoice_item_settings": [{"field_name": "ITEM_DESCRIPTION",

"display_preference": {"hidden": false

}

},

{"field_name": "ITEM_DATE",

"display_preference": {"hidden": true

}

},

{"field_name": "ITEM_TAX",

"display_preference": {"hidden": false

}

},

{"field_name": "ITEM_DISCOUNT",

"display_preference": {"hidden": false

}

}

],

"invoice_additional_settings": [{"field_name": "ATTACHMENT",

"display_preference": {"hidden": false

}

},

{"field_name": "MEMO",

"display_preference": {"hidden": false

}

},

{"field_name": "REFERENCE",

"display_preference": {"hidden": false

}

}

],

"invoice_policy_and_agreement_settings": [{"field_name": "TERMS_AND_CONDITIONS",

"display_preference": {"hidden": false

}

},

{"field_name": "PAYMENT_TERMS",

"display_preference": {"hidden": false

}

}

],

"invoice_details_settings": [{"field_name": "ORDER_DETAILS",

"display_preference": {"hidden": false

}

},

{"field_name": "PROJECT_DETAILS",

"display_preference": {"hidden": true

}

}

]

}

Response samples

application/jsonmultipart/mixedapplication/json

Sample 1 - 201 - Create Invoice with ThemeSample 1 - 201 - Create Invoice with Theme

Copy

Expand allCollapse all

`{"id": "INV2-Z56S-5LLA-Q52L-CPZ5",

"status": "DRAFT",

"detail": {"reference": "deal-ref",

"invoice_date": "2025-01-15",

"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": "2025-01-25"

"order_details": "Order #12345 placed on January 10, 2025.",

"project_details": "Website redesign project for client XYZ Corp.",

"service_details": "Consulting services provided from Jan-Mar 2025.",

"cancellation_policy": "Services may be cancelled with 14-day notice.",

"payment_terms": "Payment due within 10 days of invoice date.",

"return_policy": "All sales are final. No returns accepted after 30 days.",

"service_agreement": "Services provided as per agreement dated Jan 1, 2025.",

"tip_presets": [{"percent": "15"

},

{"percent": "20"

},

{"percent": "25"

}

],

"metadata": {"create_time": "2025-01-15T08:00:20Z",

"recipient_view_url": "https://www.api-m.paypal.com/invoice/p#Z56S5LLAQ52LCPZ5",

"invoicer_view_url": "https://www.api-m.paypal.com/invoice/details/INV2-Z56S-5LLA-Q52L-CPZ5"

}

"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": "https://example.com",

"tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",

"logo_url": "https://example.com/logo.PNG",

"additional_notes": "2-4"

"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",

"amount": {"currency_code": "USD",

"value": "3.27",

"tax_note": "Reduced tax rate"

}

},

"discount": {"percent": "5",

"amount": {"currency_code": "USD",

"value": "2.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",

"amount": {"currency_code": "USD",

"value": "0.34",

"tax_note": "Reduced tax rate"

}

},

"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,

"allow_only_pay_by_bank": true,

"tax_calculated_after_discount": true,

"show_additional_item_fields": true,

"tax_inclusive": false,

"template_id": "TEMP-19V05281TU309413B",

"theme": {"primary_color": "#4A90D9"

}

"amount": {"currency_code": "USD",

"value": "74.21",

"breakdown": {"item_total": {"currency_code": "USD",

"value": "60.00"

"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",

"amount": {"currency_code": "USD",

"value": "0.73",

"tax_note": "Reduced tax rate"

}

"discount": {"item_discount": {"currency_code": "USD",

"value": "-7.50"

"invoice_discount": {"percent": "5",

"amount": {"currency_code": "USD",

"value": "-2.63"

}

"tax_total": {"currency_code": "USD",

"value": "4.34"

}

"due_amount": {"currency_code": "USD",

"value": "74.21"

"links": [{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",

"rel": "self",

"method": "GET"

},

{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/send",

"rel": "send",

"method": "POST"

},

{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/update",

"rel": "replace",

"method": "PUT"

},

{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",

"rel": "delete",

"method": "DELETE"

},

{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/payments",

"rel": "record-payment",

"method": "POST"

},

{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/generate-qr-code",

"rel": "qr-code",

"method": "POST"

}

]

operation/invoices.list List invoices

get/v2/invoicing/invoices

Try it

Lists invoices. To filter the invoices that appear in the response, you can specify one or more optional query parameters.

SecurityOauth2

Request

query Parameters


page	integer[ 1 .. 1000 ] Default:1 The page number to be retrieved, for the list of items. So, a combination of `page=1` and `page_size=20` returns the first 20 invoices. A combination of `page=2` and `page_size=20` returns the next 20 invoices.
page_size	integer[ 1 .. 100 ] Default:20 The maximum number of invoices to return in the response.
total_required	boolean Default:false Indicates whether the to show `total_pages` and `total_items` in the response.
fields	string[ 0 .. 2147483647 ] characters^.*$ A comma-separated list of additional fields to return, if available.

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

any

Responses

200 A successful request returns the HTTP 200 OK status code and a JSON response body that lists invoices with details.

Request samples

Payload
cURL
Node.js
Java
Python

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Copy

{ }

Response samples

application/jsonmultipart/mixedapplication/json

Sample 1 - 200 - List InvoicesSample 1 - 200 - List Invoices

Copy

Expand allCollapse all

`{"total_items": 2,

"total_pages": 1,

"items": [{"id": "INV2-Z56S-5LLA-Q52L-CPZ5",

"status": "DRAFT",

"detail": {"invoice_number": "#123",

"reference": "deal-ref",

"invoice_date": "2018-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": "2018-11-22"

},

"metadata": {"create_time": "2018-11-12T08:00:20Z",

"recipient_view_url": "https://www.paypal.com/invoice/p/#Z56S5LLAQ52LCPZ5",

"invoicer_view_url": "https://www.paypal.com/invoice/details/INV2-Z56S-5LLA-Q52L-CPZ5"

}

},

"invoicer": {"email_address": "merchant@example.com"

},

"primary_recipients": [{"billing_info": {"email_address": "bill-me@example.com"

}

}

],

"amount": {"currency_code": "USD",

"value": "74.21"

},

"links": [{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",

"rel": "self",

"method": "GET"

},

{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/send",

"rel": "send",

"method": "POST"

},

{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",

"rel": "replace",

"method": "PUT"

},

{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",

"rel": "delete",

"method": "DELETE"

}

]

},

{"id": "INV2-NP6M-C9A8-ZBDA-3TEX",

"status": "SCHEDULED",

"detail": {"invoice_number": "0001",

"invoice_date": "2018-05-14",

"currency_code": "USD",

"payment_term": {"due_date": "2018-05-15"

},

"metadata": {"create_time": "2018-05-15T17:24:12Z"

}

},

"invoicer": {"email_address": "merchant@example.com"

},

"primary_recipients": [{"billing_info": {"email_address": "recipient@example.com"

}

}

],

"amount": {"currency_code": "USD",

"value": "32.00"

},

"links": [{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-NP6M-C9A8-ZBDA-3TEX",

"rel": "self",

"method": "GET"

},

{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-NP6M-C9A8-ZBDA-3TEX",

"rel": "replace",

"method": "PUT"

},

{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-NP6M-C9A8-ZBDA-3TEX",

"rel": "delete",

"method": "DELETE"

},

{"href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-NP6M-C9A8-ZBDA-3TEX/payments",

"rel": "record-payment",

"method": "POST"

}

]

}

],

"links": [{"href": "https://api-m.paypal.com/v2/invoicing/invoices?page=1&page_size=20&total_required=false",

"rel": "self",

"method": "GET"

}

]

operation/invoices.send Send invoice

post/v2/invoicing/invoices/{invoice_id}/send

Try it

Sends or schedules an invoice, by ID, to be sent to a customer. The action depends on the invoice issue date:

If the invoice issue date is current or in the past, sends the invoice immediately.
If the invoice issue date is in the future, schedules the invoice to be sent on that date.

To suppress the merchant's email notification, set the send_to_invoicer body 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 parameter does not apply to a future issue date because the invoice is scheduled to be sent through PayPal on that date.

Notes:
After you send an invoice, resending it has no effect.
To send a notification for updates, update the invoice and set the send_to_recipient body parameter to true.

SecurityOauth2

Request

path Parameters


invoice_id required	string[ 0 .. 2147483647 ] characters^.*$ The ID of the invoice to send.

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

The email or SMS notification to send to the payer when they send an invoice..


subject	string[ 0 .. 4000 ] characters^[\S\s]$ The subject of the email that is sent as a notification to the recipient. > Note:* User-provided values for this field will not be honored and the subject will always be defaulted to a system-defined value.
note	string[ 0 .. 4000 ] characters^[\S\s]$ A note to the payer. > Note:* User-provided values for this field will not be honored and the note will always be defaulted to a system-defined value.
send_to_invoicer	boolean Default:false Indicates whether to send a copy of the email to the merchant.
send_to_recipient	boolean Default:true Indicates whether to send a copy of the email to the recipient.
additional_recipients	Array of strings<ppaas_common_email_address_v2> (email_address) [ 0 .. 100 ] items An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice. > Note: Valid values are email addresses in the `additional_recipients` value associated with the invoice.

Responses

202 The server has accepted the request and will execute it at a later time.

Request samples

Payload
cURL
Node.js
Java
Python

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Sample 1 - 202 - Schedules the invoice when the issue date is in future.Sample 1 - 202 - Schedules the invoice when the issue date is in future.

Copy

`{"send_to_invoicer": true

Response samples

application/jsonmultipart/mixedapplication/json

Sample 1 - 202 - Schedules the invoice when the issue date is in future.Sample 1 - 202 - Schedules the invoice when the issue date is in future.

Copy

`{"href": "https://api-m.paypal.com/invoice/p#INV2-Z56S-5LLA-Q52L-CPZ5",

"rel": "payer-view",

"method": "GET"

operation/invoices.get Show invoice details

get/v2/invoicing/invoices/{invoice_id}

Try it

Shows details for an invoice, by ID.

SecurityOauth2

Request

path Parameters


invoice_id required	string[ 0 .. 2147483647 ] characters^.*$ The ID of the invoice for which to show details.

Responses

200 A successful request returns the HTTP 200 OK status code and a JSON response body that shows invoice details.

Request samples

cURL
Node.js
Java
Python

Copy

curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0' \
-H 'Content-Type: application/json'

Response samples

application/json

Sample 1 - 200 - Show Invoice Details with ThemeSample 1 - 200 - Show Invoice Details with Theme