Invoices API
Invoices (resource group)
Use the /invoices resource to create, update, and send invoices and invoice reminders. To manage invoices, you can also list invoices, show details for invoices, delete draft invoices, and cancel sent invoices. You can also record payments for invoices to mark them as fully or partially paid, or record refunds for invoices to mark them as fully or partially refunded. You can create QR codes for invoices that can be scanned, viewed, and paid by a mobile phone.
Generate invoice number
INVOICE-1234 is INVOICE-1235.Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/generate-next-invoice-number \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"Response
200 OK status code and a JSON response body that shows the next invoice number.invoice_numberstring
The invoice number. If you omit this value, the default is the auto-incremented number from the last number.
Sample Request
{
"invoice_number": "ee0044"
}Sample Response
{
"invoice_number": "ee0044"
}List invoices
Query parameters
fieldsstring
A comma-separated list of additional fields to return, if available.
pageinteger
The page number to be retrieved, for the list of items. So, a combination of
page=1andpage_size=20returns the first 20 invoices. A combination ofpage=2andpage_size=20returns the next 20 invoices.page_sizeinteger
The maximum number of invoices to return in the response.
total_requiredboolean
Indicates whether the to show
total_pagesandtotal_itemsin the response.
Sample Request
curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/invoices?total_required=true \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"Response
200 OK status code and a JSON response body that lists invoices with details.itemsarray (contains the invoice object)
The list of invoices that match the search criteria.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
total_itemsinteger
The total number of invoices that match the search criteria.
Note: Clients MUST NOT assume that the value of
total_itemsis constant. The value MAY change from one request to the next.total_pagesinteger
The total number of pages that are available for the search criteria.
Note: Clients MUST NOT assume that the value of total_pages is constant. The value MAY change from one request to the next
Sample Response
{
"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"
}
]
}Create draft 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..
Request body
The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.
additional_recipientsarray (contains the email_address object)
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_recipientsvalue associated with the invoice.amountThe invoice amount summary of item total, discount, tax total and shipping..
configurationThe invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
due_amountThe due amount, which is the balance amount outstanding after payments.
gratuityThe amount paid by the payer as gratuity to the invoicer.
idstring
The ID of the invoice.
invoicerThe invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
itemsarray (contains the item object)
An array of invoice line item information.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
parent_idstring
The parent ID to an invoice that defines the group invoice to which the invoice is related.
paymentsList of payments registered against the invoice..
primary_recipientsarray (contains the recipient_info object)
The billing and shipping information. Includes name, email, address, phone and language.
refundsList of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.
statusenum
The status of the invoice.
The possible values are:
DRAFT. The invoice is in draft state. It is not yet sent to the payer.SENT. The invoice has been sent to the payer. The payment is awaited from the payer.SCHEDULED. The invoice is scheduled on a future date. It is not yet sent to the payer.PAID. The payer has paid for the invoice.MARKED_AS_PAID. The invoice is marked as paid by the invoicer.CANCELLED. The invoice has been cancelled by the invoicer.REFUNDED. The invoice has been refunded by the invoicer.PARTIALLY_PAID. The payer has partially paid for the invoice.PARTIALLY_REFUNDED. The invoice has been partially refunded by the invoicer.MARKED_AS_REFUNDED. The invoice is marked as refunded by the invoicer.UNPAID. The invoicer is yet to receive the payment from the payer for the invoice.PAYMENT_PENDING. The invoicer is yet to receive the payment for the invoice. It is under pending review.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"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"
}
},
"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": "TEMP-19V05281TU309413B"
},
"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"
}
}
}
}
}'Response
201 Created status code. A JSON response body that shows invoice details is returned if you set prefer=return=representation.additional_recipientsarray (contains the email_address object)
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_recipientsvalue associated with the invoice.amountThe invoice amount summary of item total, discount, tax total and shipping..
configurationThe invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
detailThe details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.
due_amountThe due amount, which is the balance amount outstanding after payments.
gratuityThe amount paid by the payer as gratuity to the invoicer.
idstring
The ID of the invoice.
invoicerThe invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
itemsarray (contains the item object)
An array of invoice line item information.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
parent_idstring
The parent ID to an invoice that defines the group invoice to which the invoice is related.
paymentsList of payments registered against the invoice..
primary_recipientsarray (contains the recipient_info object)
The billing and shipping information. Includes name, email, address, phone and language.
refundsList of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.
statusenum
The status of the invoice.
The possible values are:
DRAFT. The invoice is in draft state. It is not yet sent to the payer.SENT. The invoice has been sent to the payer. The payment is awaited from the payer.SCHEDULED. The invoice is scheduled on a future date. It is not yet sent to the payer.PAID. The payer has paid for the invoice.MARKED_AS_PAID. The invoice is marked as paid by the invoicer.CANCELLED. The invoice has been cancelled by the invoicer.REFUNDED. The invoice has been refunded by the invoicer.PARTIALLY_PAID. The payer has partially paid for the invoice.PARTIALLY_REFUNDED. The invoice has been partially refunded by the invoicer.MARKED_AS_REFUNDED. The invoice is marked as refunded by the invoicer.UNPAID. The invoicer is yet to receive the payment from the payer for the invoice.PAYMENT_PENDING. The invoicer is yet to receive the payment for the invoice. It is under pending review.
Sample Response
{
"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.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"
},
"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",
"amount": {
"currency_code": "USD",
"value": "3.27"
}
},
"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"
}
},
"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": "TEMP-19V05281TU309413B"
},
"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"
}
}
},
"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"
}
]
}Delete invoice
Path parameters
invoice_idstring
required
The ID of the draft invoice to delete.
Sample Request
curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"Response
204 No Content status code with no JSON response body.Sample Response
204 No contentFully update invoice
invoice object. This call does not support partial updates.Query parameters
send_to_invoicerboolean
Indicates whether to send the invoice update notification to the merchant.
send_to_recipientboolean
Indicates whether to send the invoice update notification to the recipient.
Path parameters
invoice_idstring
required
The ID of the invoice to update.
Request body
The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.
additional_recipientsarray (contains the email_address object)
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_recipientsvalue associated with the invoice.amountThe invoice amount summary of item total, discount, tax total and shipping..
configurationThe invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
due_amountThe due amount, which is the balance amount outstanding after payments.
gratuityThe amount paid by the payer as gratuity to the invoicer.
idstring
The ID of the invoice.
invoicerThe invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
itemsarray (contains the item object)
An array of invoice line item information.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
parent_idstring
The parent ID to an invoice that defines the group invoice to which the invoice is related.
paymentsList of payments registered against the invoice..
primary_recipientsarray (contains the recipient_info object)
The billing and shipping information. Includes name, email, address, phone and language.
refundsList of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.
statusenum
The status of the invoice.
The possible values are:
DRAFT. The invoice is in draft state. It is not yet sent to the payer.SENT. The invoice has been sent to the payer. The payment is awaited from the payer.SCHEDULED. The invoice is scheduled on a future date. It is not yet sent to the payer.PAID. The payer has paid for the invoice.MARKED_AS_PAID. The invoice is marked as paid by the invoicer.CANCELLED. The invoice has been cancelled by the invoicer.REFUNDED. The invoice has been refunded by the invoicer.PARTIALLY_PAID. The payer has partially paid for the invoice.PARTIALLY_REFUNDED. The invoice has been partially refunded by the invoicer.MARKED_AS_REFUNDED. The invoice is marked as refunded by the invoicer.UNPAID. The invoicer is yet to receive the payment from the payer for the invoice.PAYMENT_PENDING. The invoicer is yet to receive the payment for the invoice. It is under pending review.
Sample Request
curl -v -X PUT https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"id": "INV2-C82X-JNN9-Y6S5-CNXW",
"status": "DRAFT",
"detail": {
"invoice_number": "#123",
"reference": "deal-refernce-update",
"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"
}
},
"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",
"amount": {
"currency_code": "USD",
"value": "3.27"
}
},
"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"
}
},
"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": "TEMP-19V05281TU309413B"
},
"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"
}
}
},
"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"
}
}
}
}'Response
200 OK status code. A JSON response body that shows invoice details is returned if you set prefer=return=representation.additional_recipientsarray (contains the email_address object)
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_recipientsvalue associated with the invoice.amountThe invoice amount summary of item total, discount, tax total and shipping..
configurationThe invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
detailThe details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.
due_amountThe due amount, which is the balance amount outstanding after payments.
gratuityThe amount paid by the payer as gratuity to the invoicer.
idstring
The ID of the invoice.
invoicerThe invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
itemsarray (contains the item object)
An array of invoice line item information.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
parent_idstring
The parent ID to an invoice that defines the group invoice to which the invoice is related.
paymentsList of payments registered against the invoice..
primary_recipientsarray (contains the recipient_info object)
The billing and shipping information. Includes name, email, address, phone and language.
refundsList of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.
statusenum
The status of the invoice.
The possible values are:
DRAFT. The invoice is in draft state. It is not yet sent to the payer.SENT. The invoice has been sent to the payer. The payment is awaited from the payer.SCHEDULED. The invoice is scheduled on a future date. It is not yet sent to the payer.PAID. The payer has paid for the invoice.MARKED_AS_PAID. The invoice is marked as paid by the invoicer.CANCELLED. The invoice has been cancelled by the invoicer.REFUNDED. The invoice has been refunded by the invoicer.PARTIALLY_PAID. The payer has partially paid for the invoice.PARTIALLY_REFUNDED. The invoice has been partially refunded by the invoicer.MARKED_AS_REFUNDED. The invoice is marked as refunded by the invoicer.UNPAID. The invoicer is yet to receive the payment from the payer for the invoice.PAYMENT_PENDING. The invoicer is yet to receive the payment for the invoice. It is under pending review.
Sample Response
{
"id": "INV2-C82X-JNN9-Y6S5-CNXW",
"status": "DRAFT",
"detail": {
"invoice_number": "#123",
"reference": "deal-refernce-update",
"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.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"
},
"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",
"amount": {
"currency_code": "USD",
"value": "3.27"
}
},
"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"
}
},
"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": "TEMP-19V05281TU309413B"
},
"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"
}
}
},
"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"
}
]
}Show invoice details
Path parameters
invoice_idstring
required
The ID of the invoice for which to show details.
Sample Request
curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"Response
200 OK status code and a JSON response body that shows invoice details.additional_recipientsarray (contains the email_address object)
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_recipientsvalue associated with the invoice.amountThe invoice amount summary of item total, discount, tax total and shipping..
configurationThe invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
detailThe details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.
due_amountThe due amount, which is the balance amount outstanding after payments.
gratuityThe amount paid by the payer as gratuity to the invoicer.
idstring
The ID of the invoice.
invoicerThe invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
itemsarray (contains the item object)
An array of invoice line item information.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
parent_idstring
The parent ID to an invoice that defines the group invoice to which the invoice is related.
paymentsList of payments registered against the invoice..
primary_recipientsarray (contains the recipient_info object)
The billing and shipping information. Includes name, email, address, phone and language.
refundsList of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.
statusenum
The status of the invoice.
The possible values are:
DRAFT. The invoice is in draft state. It is not yet sent to the payer.SENT. The invoice has been sent to the payer. The payment is awaited from the payer.SCHEDULED. The invoice is scheduled on a future date. It is not yet sent to the payer.PAID. The payer has paid for the invoice.MARKED_AS_PAID. The invoice is marked as paid by the invoicer.CANCELLED. The invoice has been cancelled by the invoicer.REFUNDED. The invoice has been refunded by the invoicer.PARTIALLY_PAID. The payer has partially paid for the invoice.PARTIALLY_REFUNDED. The invoice has been partially refunded by the invoicer.MARKED_AS_REFUNDED. The invoice is marked as refunded by the invoicer.UNPAID. The invoicer is yet to receive the payment from the payer for the invoice.PAYMENT_PENDING. The invoicer is yet to receive the payment for the invoice. It is under pending review.
Sample Response
{
"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": {
"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"
},
"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",
"amount": {
"currency_code": "USD",
"value": "3.27"
}
},
"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"
}
},
"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": "TEMP-19V05281TU309413B"
},
"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"
}
}
},
"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",
"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"
}
]
}Cancel sent invoice
Path parameters
invoice_idstring
required
The ID of the invoice to cancel.
Request body
additional_recipientsarray (contains the email_address object)
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_recipientsvalue associated with the invoice.notestring
A note to the payer.
send_to_invoicerboolean
Indicates whether to send a copy of the email to the merchant.
send_to_recipientboolean
Indicates whether to send a copy of the email to the recipient.
subjectstring
The subject of the email that is sent as a notification to the recipient.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/cancel \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"subject": "Invoice Cancelled",
"note": "Cancelling the invoice",
"send_to_invoicer": true,
"send_to_recipient": true,
"additional_recipients": [
"user@example.com"
]
}'Response
204 No Content status code with no JSON response body.Sample Response
204 No ContentGenerate QR code
Path parameters
invoice_idstring
required
The ID of the invoice for which to generate a QR code.
Request body
actionstring
The type of URL for which to generate a QR code. Valid values are
payanddetails.heightinteger
The height, in pixels, of the QR code image. Value is from
150to500.widthinteger
The width, in pixels, of the QR code image. Value is from
150to500.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/generate-qr-code \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"width": 400,
"height": 400
}'Response
200 OK status code and a JSON response body that shows the QR code as a PNG image.Sample Response
"--95dbdbed-7536-4c24-b5ca-bcdbc0006612 Content-Disposition: form-data; name=\"image\" Content-Type: application/octet-stream iVBORw0KGgoAAAANSUhEUgAAAJYAAACWAQAAAAAUekxPAAABxUlEQVR42u2WMY7kIBBFq0VA1n0BS1yDjCvZF7DxBdxXIuMaSFzAzgiQaz6t9mxLm1AbrCYYy4H1AlT1f9XHxH89lX7Z/2KJKN3CMIW6FCInYplLPtisoU6FTyHzti6RN5tPm+5ixrtTp0uP8g8s744eMS1yxvikNEOJz966GPTLaOL1fmjaxfAkaLCy2t2Hl10sPUIaNY1araFhCat3TbODDPkZ68Ii1sqfX62c1rzP62W8uWG0aiMaxSyvpS4hez2MzXkZg+FL4NNCwku/XtZ8g/Be550+Pe9jWj0x41rt1ngZyxzYa+NpmDjNMlYx1yhhs2glM8vY3IQ3qGWz9Tqvk7F3cGyYNd3KQDKGSWFGDjFNIZ8yhuWgR8gb5jR8+9bJ8rPUCd3oYbY4VcQqaWSYWRGcdnhnSS+D6lhKJIE5+JrTXtaquDtzuuypXrV0stRKwLAUzFodnYjxERP28ihtLw8WsbQE7JbxCD9SmxMxfsUYpiZ7lxYWMewltzuqKMz4n13tYi3vl6jW2FJQynBH+Za7Zie6sZRhNVXLTkqTmGUE5xSRu5dv3Qz3uYdj0bwkFLGWfxxoJMXx28tO9vu/9oPYF0bR/hBeOiwMAAAAAElFTkSuQmCC --95dbdbed-7536-4c24-b5ca-bcdbc0006612--"Record payment for invoice
PAID. Otherwise, the invoice is marked as PARTIALLY PAID.Path parameters
invoice_idstring
required
The ID of the invoice to mark as paid.
Request body
methodenum
required
The payment mode or method through which the invoicer can accept the payment.
The possible values are:
BANK_TRANSFER. Payments can be received through bank transfers.CASH. Payments can be received as cash.CHECK. Payments can be received as check.CREDIT_CARD. Payments can be received through credit card payments.DEBIT_CARD. Payments can be received through debit card payments.PAYPAL. Payments can be received through paypal payments.WIRE_TRANSFER. Payments can be received through wire transfer.OTHER. Payments can be received through other modes.
amountThe payment amount to record against the invoice. If you omit this parameter, the total invoice amount is marked as paid. This amount cannot exceed the amount due.
notestring
A note associated with an external cash or check payment.
payment_dateThe date when the invoice was paid, in Internet date and time format. For example, yyyy-MM-dd z.
payment_idstring
The ID for a PayPal payment transaction. Required for the
PAYPALpayment type.shipping_infoThe recipient's shipping information. Includes the user's contact information, which includes name and address.
typeenum
The payment type in an invoicing flow which can be PayPal or an external cash or check payment.
The possible values are:
PAYPAL. The payment type is PayPal.EXTERNAL. The payment type is an external cash or a check payment.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"method": "BANK_TRANSFER",
"payment_date": "2018-05-01",
"amount": {
"currency_code": "USD",
"value": "10.00"
}
}'Response
200 Created status code and a reference to the recorded payment.payment_idstring
The ID for the invoice payment.
Sample Response
{
"payment_id": "EXTR-86F38350LX4353815"
}Delete external payment
Path parameters
invoice_idstring
required
The ID of the invoice from which to delete an external payment transaction.
transaction_idstring
required
The ID of the external payment transaction to delete.
Sample Request
curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/payments/EXTR-86F38350LX4353815 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"Response
204 No Content status code with no JSON response body.Sample Response
204 No ContentRecord refund for invoice
REFUNDED. Otherwise, the invoice is marked as PARTIALLY REFUNDED.Path parameters
invoice_idstring
required
The ID of the invoice to mark as refunded.
Request body
methodenum
required
The payment mode or method through which the invoicer can accept the payments.
The possible values are:
BANK_TRANSFER. Payments can be received through bank transfers.CASH. Payments can be received as cash.CHECK. Payments can be received as check.CREDIT_CARD. Payments can be received through credit card payments.DEBIT_CARD. Payments can be received through debit card payments.PAYPAL. Payments can be received through paypal payments.WIRE_TRANSFER. Payments can be received through wire transfer.OTHER. Payments can be received through other modes.
amountThe amount to record as refunded. If you omit the amount, the total invoice paid amount is recorded as refunded.
refund_dateThe date when the invoice was refunded, in Internet date format. For example,
2014-02-27.refund_idstring
The ID for a PayPal payment transaction. Required for the
PAYPALpayment type.typeenum
The PayPal refund type. Indicates whether the refund was paid through PayPal or externally in the invoicing flow. The record refund method supports the
EXTERNALrefund type. ThePAYPALrefund type is supported for backward compatibility.The possible values are:
PAYPAL. The payment type is PayPal.EXTERNAL. The payment type is an external cash or a check payment.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/refunds \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"method": "BANK_TRANSFER",
"refund_date": "2018-05-21",
"amount": {
"currency_code": "USD",
"value": "5.00"
}
}'Response
200 Created status code and a reference to the recorded refund.refund_idstring
The ID of the refund of an invoice payment.
Sample Response
{
"refund_id": "EXTR-2LG703375E477444T"
}Delete external refund
Path parameters
invoice_idstring
required
The ID of the invoice from which to delete the external refund transaction.
transaction_idstring
required
The ID of the external refund transaction to delete.
Sample Request
curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-333R-YUQL-YNNN-D7WF/refunds/EXTR-2LG703375E477444T \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"Response
204 No Content status code with no JSON response body.Sample Response
204 No ContentSend invoice reminder
notification object that defines the subject of the reminder and other details.Path parameters
invoice_idstring
required
The ID of the invoice for which to send a reminder.
Request body
additional_recipientsarray (contains the email_address object)
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_recipientsvalue associated with the invoice.notestring
A note to the payer.
send_to_invoicerboolean
Indicates whether to send a copy of the email to the merchant.
send_to_recipientboolean
Indicates whether to send a copy of the email to the recipient.
subjectstring
The subject of the email that is sent as a notification to the recipient.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/remind \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"subject": "Reminder: Payment due for the invoice #ABC-123",
"note": "Please pay before the due date to avoid incurring late payment charges which will be adjusted in the next bill generated.",
"send_to_invoicer": true,
"additional_recipients": [
"customer-a@example.com",
"customer@example.com"
]
}'Response
204 No Content status code with no JSON response body.Sample Response
204 No ContentSend invoice
- 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.
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_recipientbody parameter totrue.
Path parameters
invoice_idstring
required
The ID of the invoice to send.
Request body
additional_recipientsarray (contains the email_address object)
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_recipientsvalue associated with the invoice.notestring
A note to the payer.
send_to_invoicerboolean
Indicates whether to send a copy of the email to the merchant.
send_to_recipientboolean
Indicates whether to send a copy of the email to the recipient.
subjectstring
The subject of the email that is sent as a notification to the recipient.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-EHNV-LJ5S-A7DZ-V6NJ/send \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: b1d1f06c7246c" \
-d '{
"send_to_invoicer": true
}'Response
202 Accepted status code with no JSON response body, when the invoice issue date is in future.linksarray (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
202 AcceptedSearch invoices (resource group)
Use the /search-invoices resource to search for and list invoices that match search criteria.
Search for invoices
Query parameters
pageinteger
The page number to be retrieved, for the list of items. So, a combination of
page=1andpage_size=20returns the first 20 invoices. A combination ofpage=2andpage_size=20returns the next 20 invoices.page_sizeinteger
The page size for the search results.
total_requiredboolean
Indicates whether the to show
total_pagesandtotal_itemsin the response.
Request body
archivedboolean
Indicates whether to list merchant-archived invoices in the response. Value is:
true. Response lists only merchant-archived invoices.false. Response lists only unarchived invoices.null. Response lists all invoices.
creation_date_rangeFilters the search by a creation date range for the invoice, in Internet date and time format.
currency_codeThe three-character ISO-4217 currency code that identifies the currency.
due_date_rangeFilters the search by a due date range for the invoice, in Internet date and time format.
fieldsarray (contains the field object)
A CSV file of fields to return for the user, if available. Because the invoice object can be very large, field filtering is required. Valid collection fields are
items,payments,refunds,additional_recipients_info, andattachments.invoice_date_rangeFilters the search by a date range for the invoice, in Internet date and time format.
invoice_numberstring
Filters the search by the invoice number.
memostring
A private bookkeeping memo for the user.
payment_date_rangeThe date and time range. Filters invoices by creation date, invoice date, due date, and payment date.
recipient_business_namestring
Filters the search by the recipient business name.
recipient_emailstring
Filters the search by the email address.
recipient_first_namestring
Filters the search by the recipient first name.
recipient_last_namestring
Filters the search by the recipient last name.
referencestring
The reference data, such as a PO number.
statusarray (contains the invoice_status object)
An array of status values.
total_amount_rangeFilters the search by the total amount.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/search-invoices?page=1&page_size=1&total_required=true \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"total_amount_range": {
"lower_amount": {
"currency_code": "USD",
"value": "50.00"
},
"upper_amount": {
"currency_code": "USD",
"value": "50.00"
}
},
"invoice_date_range": {
"start": "2018-06-01",
"end": "2018-06-21"
}
}'Response
200 OK status code and a JSON response body that lists the invoices that match the search criteria.itemsarray (contains the invoice object)
The list of invoices that match the search criteria.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
total_itemsinteger
The total number of invoices that match the search criteria.
Note: Clients MUST NOT assume that the value of
total_itemsis constant. The value MAY change from one request to the next.total_pagesinteger
The total number of pages that are available for the search criteria.
Note: Clients MUST NOT assume that the value of total_pages is constant. The value MAY change from one request to the next
Sample Response
{
"total_items": 6,
"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.api-m.paypal.com/invoice/p#Z56S5LLAQ52LCPZ5",
"invoicer_view_url": "https://www.api-m.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"
}
]
}
],
"links": [
{
"href": "https://api-m.paypal.com/v2/invoicing/invoices?page=2&page_size=10&total_required=true",
"rel": "next",
"method": "POST"
}
]
}Templates (resource group)
Use the /templates resource to create, list, show details for, update, and delete invoice templates. Use the /templates resource when you create a third-party invoicing application. For instance, a business can create a template with predefined invoice data. Later, the business can select the template to populate the invoice data.
Note: To upload a logo to display on an invoice, you can use the Template Settings dashboard to create a template. When you create an invoice, you can use the URI for that logo.
List templates
The user can select which values to show in the business information section of their template.
Query parameters
fieldsstring
The fields to return in the response. Value is
allornone. To return only the template name, ID, and default attributes, specifynone.pageinteger
The page number to be retrieved, for the list of templates. So, a combination of
page=1andpage_size=20returns the first 20 templates. A combination ofpage=2andpage_size=20returns the next 20 templates.page_sizeinteger
The maximum number of templates to return in the response.
Sample Request
curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/templates \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"Response
200 OK status code and a JSON response body that lists invoices.addressesarray (contains the address_portable object)
An array of addresses in the user's PayPal profile.
emailsAn array of emails in the user's PayPal profile.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
phonesarray (contains the phone_detail object)
An array of phone numbers in the user's PayPal profile.
templatesarray (contains the template object)
An array of details for each template. If
fieldsisnone, returns only the template name, ID, and default status.
Sample Response
{
"addresses": [
{
"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"
},
{
"address_line_1": "26303 E 8216 N",
"address_line_2": "045608 Ocean Bay Plaza #02",
"admin_area_2": "Garden City",
"admin_area_1": "NY",
"postal_code": "11530",
"country_code": "US"
}
],
"emails": "email@example.com, email2@example.com",
"phones": [
{
"country_code": "001",
"national_number": "4085551234",
"phone_type": "HOME"
},
{
"country_code": "1",
"national_number": "3477832250",
"phone_type": "MOBILE"
},
{
"country_code": "1",
"national_number": "3479543267",
"phone_type": "FAX"
},
{
"country_code": "1",
"national_number": "7183514942",
"phone_type": "OTHER"
}
],
"templates": [
{
"id": "TEMP-19V05281TU309413B",
"name": "reference-temp",
"default_template": true,
"template_info": {
"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"
}
}
},
"detail": {
"reference": "deal-ref",
"currency_code": "USD",
"note": "Thank you for your business.",
"terms_and_conditions": "No refunds after 30 days.",
"memo": "This is a long contract",
"attachments": [
{
"id": "Screen Shot 2018-11-23 at 16.45.01.png",
"reference_url": "https://exxample.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE"
}
],
"payment_term": {
"term_type": "NET_10"
},
"metadata": {
"create_time": "2018-12-03T03:38:46z"
}
},
"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": "MOBILE"
}
],
"additional_info": "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"
}
}
}
],
"additional_recipients": [
"inform-me@example.com"
],
"items": [
{
"id": "ITEM-9R873787D1610780X",
"name": "Yoga Mat",
"description": "new watch",
"quantity": "1",
"unit_amount": {
"currency_code": "USD",
"value": "50.00"
},
"tax": {
"id": "TAX-9R873787D1610780X",
"name": "Sales Tax",
"percent": "7.25",
"amount": {
"currency_code": "USD",
"value": "3.27"
}
},
"discount": {
"percent": "5",
"amount": {
"currency_code": "USD",
"value": "2.5"
}
},
"unit_of_measure": "QUANTITY"
},
{
"id": "ITEM-4XD34145EH4061035",
"name": "Yoga t-shirt",
"quantity": "1",
"unit_amount": {
"currency_code": "USD",
"value": "10.00"
},
"tax": {
"id": "TAX-4XD34145EH4061035",
"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"
}
],
"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"
}
}
},
"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"
}
}
}
},
"settings": {
"template_item_settings": [
{
"field_name": "items.date",
"display_preference": {
"hidden": true
}
},
{
"field_name": "items.discount",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.tax",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.description",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.quantity",
"display_preference": {
"hidden": true
}
}
],
"template_subtotal_settings": [
{
"field_name": "custom",
"display_preference": {
"hidden": false
}
},
{
"field_name": "discount",
"display_preference": {
"hidden": false
}
},
{
"field_name": "shipping",
"display_preference": {
"hidden": false
}
}
]
},
"unit_of_measure": "QUANTITY",
"standard_template": false,
"links": [
{
"href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
"rel": "self",
"method": "GET"
}
]
},
{
"default_template": true,
"id": "TEMP-11E67842VH3080617",
"name": "Quantity",
"template_info": {
"invoicer": {
"name": {
"given_name": "David",
"surname": "Larusso"
},
"email_address": "bill-me@example.com"
},
"detail": {
"currency_code": "USD"
}
},
"standard_template": false,
"links": [
{
"href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-11E67842VH3080617",
"rel": "self",
"method": "GET"
}
]
},
{
"default_template": false,
"id": "TEMP-6HC14139B8663074X",
"name": "Hours",
"template_info": {
"invoicer": {
"name": {
"given_name": "David",
"surname": "Larusso"
},
"email_address": "bill-me@example.com"
},
"detail": {
"currency_code": "USD"
}
},
"standard_template": false,
"links": [
{
"href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-6HC14139B8663074X",
"rel": "self",
"method": "GET"
}
]
}
]
}Create template
Note: Every merchant starts with three PayPal system templates that are optimized for the unit type billed. The template includesQuantity,Hours, andAmount.
Request body
default_templateboolean
Indicates whether this template is the default template. A invoicer can have one default template.
idstring
The ID of the template.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
namestring
The template name.
Note: The template name must be unique.
settingsThe template settings. Describes which fields to show or hide when you create an invoice.
standard_templateboolean
Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.
template_infoThe template details. Includes invoicer business information, invoice recipients, items, and configuration.
unit_of_measureenum
The unit of measure for the template. Value is quantity, hours, or amount.
The possible values are:
QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.HOURS. The unit of measure is hours. This invoice template is typically used for services.AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/templates \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"default_template": true,
"template_info": {
"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"
}
}
},
"detail": {
"reference": "deal-ref",
"note": "Thank you for your business.",
"currency_code": "USD",
"terms_and_conditions": "No refunds after 30 days.",
"memo": "This is a long contract",
"attachments": [
{
"id": "Screen Shot 2018-11-23 at 16.45.01.png",
"reference_url": "https://api-m.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE"
}
],
"payment_term": {
"term_type": "NET_10"
}
},
"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": "MOBILE"
}
],
"additional_info": "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"
}
}
}
],
"additional_recipients": [
"inform-me@example.com"
],
"items": [
{
"name": "Yoga Mat",
"description": "new watch",
"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"
}
],
"amount": {
"currency_code": "USD",
"value": "74.21",
"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": {
"template_item_settings": [
{
"field_name": "items.date",
"display_preference": {
"hidden": true
}
},
{
"field_name": "items.discount",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.tax",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.description",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.quantity",
"display_preference": {
"hidden": true
}
}
],
"template_subtotal_settings": [
{
"field_name": "custom",
"display_preference": {
"hidden": false
}
},
{
"field_name": "discount",
"display_preference": {
"hidden": false
}
},
{
"field_name": "shipping",
"display_preference": {
"hidden": false
}
}
]
},
"unit_of_measure": "QUANTITY",
"standard_template": false
}'Response
201 Created status code. A JSON response body that shows template details is returned if you set prefer=return=representation.default_templateboolean
Indicates whether this template is the default template. A invoicer can have one default template.
idstring
The ID of the template.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
namestring
The template name.
Note: The template name must be unique.
settingsThe template settings. Describes which fields to show or hide when you create an invoice.
standard_templateboolean
Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.
template_infoThe template details. Includes invoicer business information, invoice recipients, items, and configuration.
unit_of_measureenum
The unit of measure for the template. Value is quantity, hours, or amount.
The possible values are:
QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.HOURS. The unit of measure is hours. This invoice template is typically used for services.AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.
Sample Response
{
"id": "TEMP-19V05281TU309413B",
"name": "reference-temp",
"default_template": true,
"template_info": {
"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"
}
}
},
"detail": {
"reference": "deal-ref",
"note": "Thank you for your business.",
"currency_code": "USD",
"terms_and_conditions": "No refunds after 30 days.",
"memo": "This is a long contract",
"attachments": [
{
"id": "Screen Shot 2018-11-23 at 16.45.01.png",
"reference_url": "https://api-m.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE"
}
],
"payment_term": {
"term_type": "NET_10"
},
"metadata": {
"create_time": "2018-12-03T03:38:46z"
}
},
"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": "MOBILE"
}
],
"additional_info": "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"
}
}
}
],
"additional_recipients": [
"inform-me@example.com"
],
"items": [
{
"id": "ITEM-9R873787D1610780X",
"name": "Yoga Mat",
"description": "new watch",
"quantity": "1",
"unit_amount": {
"currency_code": "USD",
"value": "50.00"
},
"tax": {
"id": "TAX-9R873787D1610780X",
"name": "Sales Tax",
"percent": "7.25",
"amount": {
"currency_code": "USD",
"value": "3.27"
}
},
"discount": {
"percent": "5",
"amount": {
"currency_code": "USD",
"value": "2.5"
}
},
"unit_of_measure": "QUANTITY"
},
{
"id": "ITEM-4XD34145EH4061035",
"name": "Yoga T Shirt",
"quantity": "1",
"unit_amount": {
"currency_code": "USD",
"value": "10.00"
},
"tax": {
"id": "TAX-4XD34145EH4061035",
"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"
}
],
"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"
}
}
},
"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"
}
}
}
},
"settings": {
"template_item_settings": [
{
"field_name": "items.date",
"display_preference": {
"hidden": true
}
},
{
"field_name": "items.discount",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.tax",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.description",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.quantity",
"display_preference": {
"hidden": true
}
}
],
"template_subtotal_settings": [
{
"field_name": "custom",
"display_preference": {
"hidden": false
}
},
{
"field_name": "discount",
"display_preference": {
"hidden": false
}
},
{
"field_name": "shipping",
"display_preference": {
"hidden": false
}
}
]
},
"unit_of_measure": "QUANTITY",
"standard_template": false,
"links": [
{
"href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
"rel": "delete",
"method": "DELETE"
},
{
"href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
"rel": "replace",
"method": "PUT"
}
]
}Delete template
Path parameters
template_idstring
required
The ID of the template to delete.
Sample Request
curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"Response
204 No Content status code with no JSON response body.Sample Response
204 No ContentFully update template
template object. This call does not support partial updates.Path parameters
template_idstring
required
The ID of the template for which to show details.
Request body
default_templateboolean
Indicates whether this template is the default template. A invoicer can have one default template.
idstring
The ID of the template.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
namestring
The template name.
Note: The template name must be unique.
settingsThe template settings. Describes which fields to show or hide when you create an invoice.
standard_templateboolean
Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.
template_infoThe template details. Includes invoicer business information, invoice recipients, items, and configuration.
unit_of_measureenum
The unit of measure for the template. Value is quantity, hours, or amount.
The possible values are:
QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.HOURS. The unit of measure is hours. This invoice template is typically used for services.AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.
Sample Request
curl -v -X PUT https://api-m.sandbox.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"default_template": true,
"template_info": {
"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"
}
}
},
"detail": {
"reference": "deal-reference-value",
"note": "Thank you for your business.",
"currency_code": "USD",
"terms_and_conditions": "No refunds after 30 days.",
"memo": "This is a long contract",
"attachments": [
{
"id": "Screen Shot 2018-11-23 at 16.45.01.png",
"reference_url": "https://example.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE"
}
],
"payment_term": {
"term_type": "NET_10"
}
},
"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": "MOBILE"
}
],
"additional_info": "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"
}
}
}
],
"additional_recipients": [
"inform-me@example.com"
],
"items": [
{
"name": "Yoga Mat",
"description": "new watch",
"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"
}
],
"amount": {
"currency_code": "USD",
"value": "74.21",
"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": {
"template_item_settings": [
{
"field_name": "items.date",
"display_preference": {
"hidden": true
}
},
{
"field_name": "items.discount",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.tax",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.description",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.quantity",
"display_preference": {
"hidden": true
}
}
],
"template_subtotal_settings": [
{
"field_name": "custom",
"display_preference": {
"hidden": false
}
},
{
"field_name": "discount",
"display_preference": {
"hidden": false
}
},
{
"field_name": "shipping",
"display_preference": {
"hidden": false
}
}
]
},
"unit_of_measure": "QUANTITY",
"standard_template": false
}'Response
200 OK status code. A JSON response body that shows template details is returned if you set prefer=return=representation.default_templateboolean
Indicates whether this template is the default template. A invoicer can have one default template.
idstring
The ID of the template.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
namestring
The template name.
Note: The template name must be unique.
settingsThe template settings. Describes which fields to show or hide when you create an invoice.
standard_templateboolean
Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.
template_infoThe template details. Includes invoicer business information, invoice recipients, items, and configuration.
unit_of_measureenum
The unit of measure for the template. Value is quantity, hours, or amount.
The possible values are:
QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.HOURS. The unit of measure is hours. This invoice template is typically used for services.AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.
Sample Response
{
"id": "TEMP-19V05281TU309413B",
"name": "reference-temp",
"default_template": true,
"template_info": {
"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"
}
}
},
"detail": {
"reference": "deal-reference-value",
"currency_code": "USD",
"note": "Thank you for your business.",
"terms_and_conditions": "No refunds after 30 days.",
"memo": "This is a long contract",
"attachments": [
{
"id": "Screen Shot 2018-11-23 at 16.45.01.png",
"reference_url": "https://api-m.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE"
}
],
"payment_term": {
"term_type": "NET_10"
},
"metadata": {
"create_time": "2018-12-03T03:38:46z"
}
},
"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": "MOBILE"
}
],
"additional_info": "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"
}
}
}
],
"additional_recipients": [
"inform-me@example.com"
],
"items": [
{
"id": "ITEM-9R873787D1610780X",
"name": "Yoga Mat",
"description": "new watch",
"quantity": "1",
"unit_amount": {
"currency_code": "USD",
"value": "50.00"
},
"tax": {
"id": "TAX-9R873787D1610780X",
"name": "Sales Tax",
"percent": "7.25",
"amount": {
"currency_code": "USD",
"value": "3.27"
}
},
"discount": {
"percent": "5",
"amount": {
"currency_code": "USD",
"value": "2.5"
}
},
"unit_of_measure": "QUANTITY"
},
{
"id": "ITEM-4XD34145EH4061035",
"name": "Yoga T Shirt",
"quantity": "1",
"unit_amount": {
"currency_code": "USD",
"value": "10.00"
},
"tax": {
"id": "TAX-4XD34145EH4061035",
"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"
}
],
"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"
}
}
},
"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"
}
}
}
},
"settings": {
"template_item_settings": [
{
"field_name": "items.date",
"display_preference": {
"hidden": true
}
},
{
"field_name": "items.discount",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.tax",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.description",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.quantity",
"display_preference": {
"hidden": true
}
}
],
"template_subtotal_settings": [
{
"field_name": "custom",
"display_preference": {
"hidden": false
}
},
{
"field_name": "discount",
"display_preference": {
"hidden": false
}
},
{
"field_name": "shipping",
"display_preference": {
"hidden": false
}
}
]
},
"unit_of_measure": "QUANTITY",
"standard_template": false,
"links": [
{
"href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
"rel": "delete",
"method": "DELETE"
},
{
"href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
"rel": "replace",
"method": "PUT"
}
]
}Show template details
Path parameters
template_idstring
required
The ID of the template for which to show details.
Sample Request
curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"Response
200 OK status code and a JSON response body that shows template details.default_templateboolean
Indicates whether this template is the default template. A invoicer can have one default template.
idstring
The ID of the template.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
namestring
The template name.
Note: The template name must be unique.
settingsThe template settings. Describes which fields to show or hide when you create an invoice.
standard_templateboolean
Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.
template_infoThe template details. Includes invoicer business information, invoice recipients, items, and configuration.
unit_of_measureenum
The unit of measure for the template. Value is quantity, hours, or amount.
The possible values are:
QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.HOURS. The unit of measure is hours. This invoice template is typically used for services.AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.
Sample Response
{
"id": "TEMP-19V05281TU309413B",
"name": "reference-temp",
"default_template": true,
"template_info": {
"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"
}
}
},
"detail": {
"reference": "deal-ref",
"currency_code": "USD",
"note": "Thank you for your business.",
"terms_and_conditions": "No refunds after 30 days.",
"memo": "This is a long contract",
"attachments": [
{
"id": "Screen Shot 2018-11-23 at 16.45.01.png",
"reference_url": "https://api-m.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE"
}
],
"payment_term": {
"term_type": "NET_10"
},
"metadata": {
"create_time": "2018-12-03T03:38:46z"
}
},
"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": "MOBILE"
}
],
"additional_info": "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"
}
}
}
],
"additional_recipients": [
"inform-me@example.com"
],
"items": [
{
"id": "ITEM-9R873787D1610780X",
"name": "Yoga Mat",
"description": "new watch",
"quantity": "1",
"unit_amount": {
"currency_code": "USD",
"value": "50.00"
},
"tax": {
"id": "TAX-9R873787D1610780X",
"name": "Sales Tax",
"percent": "7.25",
"amount": {
"currency_code": "USD",
"value": "3.27"
}
},
"discount": {
"percent": "5",
"amount": {
"currency_code": "USD",
"value": "2.5"
}
},
"unit_of_measure": "QUANTITY"
},
{
"id": "ITEM-4XD34145EH4061035",
"name": "Yoga T Shirt",
"quantity": "1",
"unit_amount": {
"currency_code": "USD",
"value": "10.00"
},
"tax": {
"id": "TAX-4XD34145EH4061035",
"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"
}
],
"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"
}
}
},
"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"
}
}
}
},
"settings": {
"template_item_settings": [
{
"field_name": "items.date",
"display_preference": {
"hidden": true
}
},
{
"field_name": "items.discount",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.tax",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.description",
"display_preference": {
"hidden": false
}
},
{
"field_name": "items.quantity",
"display_preference": {
"hidden": true
}
}
],
"template_subtotal_settings": [
{
"field_name": "custom",
"display_preference": {
"hidden": false
}
},
{
"field_name": "discount",
"display_preference": {
"hidden": false
}
},
{
"field_name": "shipping",
"display_preference": {
"hidden": false
}
}
]
},
"unit_of_measure": "QUANTITY",
"standard_template": false,
"links": [
{
"href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
"rel": "delete",
"method": "DELETE"
},
{
"href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
"rel": "replace",
"method": "PUT"
}
]
}Common object definitions
202_response
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
account_id
account_idstring
The account identifier for a PayPal account.
address_details
building_namestring
A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example,
Craven House.delivery_servicestring
The delivery service. Post office box, bag number, or post office name.
street_namestring
The street name. Just
DruryinDrury Lane.street_numberstring
The street number.
street_typestring
The street type. For example, avenue, boulevard, road, or expressway.
sub_buildingstring
The first-order entity below a named building or location that represents the sub-premises. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
address_portable
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GBand notUKas used in the top-level domain names for that country. Use theC2country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.address_detailsThe non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.
For example,address_portable.address_line_1is usually a combination ofaddress_details.street_number,street_name, andstreet_type.address_line_1string
The first line of the address. For example, number or street. For example,
173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.address_line_2string
The second line of the address. For example, suite or apartment number.
address_line_3string
The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as
next to Walmart, or a landmark in an Indian address.admin_area_1string
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example,
CAand notCalifornia. Value, by country, is:- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
admin_area_2string
A city, town, or village. Smaller than
admin_area_level_1.admin_area_3string
A sub-locality, suburb, neighborhood, or district. Smaller than
admin_area_level_2. Value is:- Brazil. Suburb, bairro, or neighborhood.
- India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.
admin_area_4string
The neighborhood, ward, or district. Smaller than
admin_area_level_3orsub_locality. Value is:- The postal sorting code for Guernsey and many French territories, such as French Guiana.
- The fine-grained administrative levels in China.
postal_codestring
The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
address_portable
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GBand notUKas used in the top-level domain names for that country. Use theC2country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.address_detailsThe non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.
For example,address_portable.address_line_1is usually a combination ofaddress_details.street_number,street_name, andstreet_type.address_line_1string
The first line of the address. For example, number or street. For example,
173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.address_line_2string
The second line of the address. For example, suite or apartment number.
address_line_3string
The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as
next to Walmart, or a landmark in an Indian address.admin_area_1string
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example,
CAand notCalifornia. Value, by country, is:- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
admin_area_2string
A city, town, or village. Smaller than
admin_area_level_1.admin_area_3string
A sub-locality, suburb, neighborhood, or district. Smaller than
admin_area_level_2. Value is:- Brazil. Suburb, bairro, or neighborhood.
- India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.
admin_area_4string
The neighborhood, ward, or district. Smaller than
admin_area_level_3orsub_locality. Value is:- The postal sorting code for Guernsey and many French territories, such as French Guiana.
- The fine-grained administrative levels in China.
postal_codestring
The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
address_portable_postal_code_validation
address_portable_postal_code_validation
address_portable_postal_code_validation
address_portable_postal_code_validation
amount_summary_detail
breakdownThe breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, custom amount, shipping and discounts, if any.
currency_codeThe three-character ISO-4217 currency code that identifies the currency.
valuestring
The value, which might be:
- An integer for currencies like
JPYthat are not typically fractional. - A decimal fraction for currencies like
TNDthat are subdivided into thousandths.
- An integer for currencies like
amount_with_breakdown
customThe custom amount to apply to an invoice. If you include a label, you must include the custom amount.
discountThe discount can be at the item or invoice level, or both. Can be applied as a percent or amount. If you provide both amount and percent, amount takes precedent.
item_totalThe subtotal for all items. Must equal the sum of (
items[].unit_amount*items[].quantity) for all items.shippingThe shipping fee for all items. Includes tax on shipping.
tax_totalThe aggregated amount of the item and shipping taxes.
billing_info
additional_infostring
Any additional information about the recipient.
email_addressThe invoice recipient email address. If you omit this value, the invoice is payable and a notification email is not sent.
languageThe language in which to show the invoice recipient's email message. Used only when the recipient does not have a PayPal account. If you omit the language and the recipient does not have a PayPal account, the email message is sent in the language of the merchant's PayPal account.
phonesarray (contains the phone_detail object)
The invoice recipient's phone numbers. Extension number is not supported.
business_name
business_namestring
Required. The business name of the party.
business_name_validation
business_name_validation
configuration
allow_tipboolean
Indicates whether the invoice enables the customer to enter a tip amount during payment. If
true, the invoice shows a tip amount field so that the customer can enter a tip amount. Iffalse, the invoice does not show a tip amount field.Note: This feature is not available for users in
Hong Kong,Taiwan,India, orJapan.partial_paymentThe partial payment details. Includes the minimum amount that the invoicer wants the payer to pay.
tax_calculated_after_discountboolean
Indicates whether the tax is calculated before or after a discount. If
false, the tax is calculated before a discount. Iftrue, the tax is calculated after a discount.tax_inclusiveboolean
Indicates whether the unit price includes tax.
template_idstring
The template ID. The template determines the layout of the invoice. Includes which fields to show and hide.
country_code
country_codestring
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GBand notUKas used in the top-level domain names for that country. Use theC2country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
country_code
country_codestring
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GBand notUKas used in the top-level domain names for that country. Use theC2country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
currency_code
currency_codestring
The three-character ISO-4217 currency code that identifies the currency.
custom_amount
labelstring
required
The label to the custom amount of the invoice.
amountThe custom amount value. Value is from
-1000000to1000000. Supports up to two decimal places.
date_no_time
date_no_timestring
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard
date_timetype. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
date_no_time
date_no_timestring
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard
date_timetype. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
date_time
date_timestring
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
date_time_range
The end date of the range. Filters invoices by creation date, invoice date, due date, and payment date.
Note: The regular expression provides guidance but does not reject all invalid dates.
Minimum length: 20.
Maximum length: 64
Pattern:^0-9{4}-(01-9|10-2)-(01-9|1-2|30-1)T,t:0-5:(0-5|60)(.+)?(Zz|+-{2}:0-9{2})$The start date of the range. Filters invoices by creation date, invoice date, due date, and payment date.
detail
The three-character ISO-4217 currency code that identifies the currency.
attachmentsarray (contains the file_reference object)
An array of PayPal IDs for the files that are attached to an invoice.
memostring
A private bookkeeping memo for the user.
notestring
A note to the invoice recipient. Also appears on the invoice notification email.
referencestring
The reference data. Includes a post office (PO) number.
terms_and_conditionsstring
The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.
emailstring
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the
@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
email_address
email_addressstring
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the
@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
error
debug_idstring
required
The PayPal internal ID. Used for correlation purposes.
messagestring
required
The message that describes the error.
namestring
required
The human-readable, unique name of the error.
detailsarray (contains the error_details object)
An array of additional details about the error.
information_linkstring
The information link, or URI, that shows detailed information about this error for the developer.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
error_details
issuestring
required
The unique, fine-grained application-level error code.
descriptionstring
The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
fieldstring
The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
locationstring
The location of the field that caused the error. Value is
body,path, orquery.valuestring
The value of the field that caused the error.
field
fieldstring
The name of the field.
file_reference
content_typestring
create_timeThe date and time when the file was created, in Internet date and time format.
idstring
The ID of the referenced file.
reference_urlstring
The reference URL for the file.
sizestring
The size of the file, in bytes.
invoice
The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.
additional_recipientsarray (contains the email_address object)
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_recipientsvalue associated with the invoice.amountThe invoice amount summary of item total, discount, tax total and shipping..
configurationThe invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
due_amountThe due amount, which is the balance amount outstanding after payments.
gratuityThe amount paid by the payer as gratuity to the invoicer.
idstring
The ID of the invoice.
invoicerThe invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
itemsarray (contains the item object)
An array of invoice line item information.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
parent_idstring
The parent ID to an invoice that defines the group invoice to which the invoice is related.
paymentsList of payments registered against the invoice..
primary_recipientsarray (contains the recipient_info object)
The billing and shipping information. Includes name, email, address, phone and language.
refundsList of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.
statusenum
The status of the invoice.
The possible values are:
DRAFT. The invoice is in draft state. It is not yet sent to the payer.SENT. The invoice has been sent to the payer. The payment is awaited from the payer.SCHEDULED. The invoice is scheduled on a future date. It is not yet sent to the payer.PAID. The payer has paid for the invoice.MARKED_AS_PAID. The invoice is marked as paid by the invoicer.CANCELLED. The invoice has been cancelled by the invoicer.REFUNDED. The invoice has been refunded by the invoicer.PARTIALLY_PAID. The payer has partially paid for the invoice.PARTIALLY_REFUNDED. The invoice has been partially refunded by the invoicer.MARKED_AS_REFUNDED. The invoice is marked as refunded by the invoicer.UNPAID. The invoicer is yet to receive the payment from the payer for the invoice.PAYMENT_PENDING. The invoicer is yet to receive the payment for the invoice. It is under pending review.
invoice_creation_flow
invoice_creation_flowenum
The frequency at which the invoice is sent:
- Multiple recipient. Sent to multiple recipients.
- Batch. Sent in a batch.
- Regular single. Sent one time to a single recipient.
The possible values are:
MULTIPLE_RECIPIENTS_GROUP. The invoice sent to multiple recipients.BATCH. The invoice sent as a batch.REGULAR_SINGLE. The regular invoice sent to single recipient.
invoice_detail
The three-character ISO-4217 currency code that identifies the currency.
attachmentsarray (contains the file_reference object)
An array of PayPal IDs for the files that are attached to an invoice.
memostring
A private bookkeeping memo for the user.
notestring
A note to the invoice recipient. Also appears on the invoice notification email.
referencestring
The reference data. Includes a post office (PO) number.
terms_and_conditionsstring
The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.
invoice_dateThe invoice date as specificed by the sender, in Internet date and time format. Only UTC is supported in response. For example, yyyy-MM-ddTz.
invoice_numberstring
The invoice number. Default is the number that is auto-incremented number from the last number.
metadataThe audit metadata. Captures all invoicing actions on create, send, update, and cancel.
payment_termThe payment due date for the invoice. Value is either but not both
term_typeordue_date.
invoice_number
invoice_numberstring
The invoice number. If you omit this value, the default is the auto-incremented number from the last number.
invoice_payment_term
term_typeThe payment term. Payment can be due upon receipt, a specified date, or in a set number of days.
due_dateThe date when the invoice payment is due, in Internet date and time format. For example, yyyy-MM-ddTz.
invoice_status
invoice_statusenum
The status of the invoice.
The possible values are:
DRAFT. The invoice is in draft state. It is not yet sent to the payer.SENT. The invoice has been sent to the payer. The payment is awaited from the payer.SCHEDULED. The invoice is scheduled on a future date. It is not yet sent to the payer.PAID. The payer has paid for the invoice.MARKED_AS_PAID. The invoice is marked as paid by the invoicer.CANCELLED. The invoice has been cancelled by the invoicer.REFUNDED. The invoice has been refunded by the invoicer.PARTIALLY_PAID. The payer has partially paid for the invoice.PARTIALLY_REFUNDED. The invoice has been partially refunded by the invoicer.MARKED_AS_REFUNDED. The invoice is marked as refunded by the invoicer.UNPAID. The invoicer is yet to receive the payment from the payer for the invoice.PAYMENT_PENDING. The invoicer is yet to receive the payment for the invoice. It is under pending review.
invoicer_info
additional_notesstring
Any additional information. Includes business hours.
email_addressThe invoicer email address, which must be listed in the user's PayPal profile. If you omit this value, notifications are sent from and to the primary email address but do not appear on the invoice.
logo_urlstring
The full URL to an external logo image. The logo image must not be larger than 250 pixels wide by 90 pixels high.
phonesarray (contains the phone_detail object)
An array of invoicer's phone numbers. The invoicer can choose to hide the phone number on the invoice.
tax_idstring
The invoicer's tax ID.
websitestring
The invoicer's website.
invoices
itemsarray (contains the invoice object)
The list of invoices that match the search criteria.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
total_itemsinteger
The total number of invoices that match the search criteria.
Note: Clients MUST NOT assume that the value of
total_itemsis constant. The value MAY change from one request to the next.total_pagesinteger
The total number of pages that are available for the search criteria.
Note: Clients MUST NOT assume that the value of total_pages is constant. The value MAY change from one request to the next
item
namestring
required
The item name for the invoice line item.
quantitystring
required
The quantity of the item that the invoicer provides to the payer. Value is from
-1000000to1000000. Supports up to five decimal places.The unit price of the item. This does not include tax and discount. Value is from
-1000000to1000000. Supports up to two decimal places.descriptionstring
The item description for the invoice line item.
discountDiscount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.
idstring
The ID of the invoice line item.
item_dateThe date when the item or service was provided, in Internet date and time format. For example, yyyy-MM-ddTz.
taxThe tax associated with the item. The tax amount is added to the item total. Value is from
0to100. Supports up to five decimal places.unit_of_measureenum
The unit of measure for the invoiced item. For
AMOUNTtheunit_amountandquantityare not shown on the invoice.Note: If your specify different
unit_of_measurevalues for the same invoice, the invoice uses the first value.The possible values are:
QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.HOURS. The unit of measure is hours. This invoice template is typically used for services.AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.
language
languagestring
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code.
link_description
hrefstring
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the
$,(, and)characters. Thehrefis the key HATEOAS component that links a completed call with a subsequent call.relstring
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
methodenum
The HTTP method required to make the related call.
metadata
create_timeThe date and time when the resource was created, in Internet date and time format.
created_bystring
The email address of the account that created the resource.
last_update_timeThe date and time when the resource was last edited, in Internet date and time format.
last_updated_bystring
The email address of the account that last edited the resource.
cancel_timeThe date and time when the resource was canceled, in Internet date and time format.
cancelled_bystring
The actor who canceled the resource.
created_by_flowThe flow variation that created this invoice.
first_sent_timeThe date and time when the resource was first sent, in Internet date and time format.
invoicer_view_urlstring
The URL for the invoice merchant view hosted on paypal.com.
last_sent_bystring
The email address of the account that last sent the resource.
last_sent_timeThe date and time when the resource was last sent, in Internet date and time format.
recipient_view_urlstring
The URL for the invoice payer view hosted on paypal.com.
money
The three-character ISO-4217 currency code that identifies the currency.
valuestring
required
The value, which might be:
- An integer for currencies like
JPYthat are not typically fractional. - A decimal fraction for currencies like
TNDthat are subdivided into thousandths.
- An integer for currencies like
name
alternate_full_namestring
DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.
full_namestring
When the party is a person, the party's full name.
given_namestring
When the party is a person, the party's given, or first, name.
middle_namestring
When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
prefixstring
The prefix, or title, to the party's name.
suffixstring
The suffix for the party's name.
surnamestring
When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
name
alternate_full_namestring
DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.
full_namestring
When the party is a person, the party's full name.
given_namestring
When the party is a person, the party's given, or first, name.
middle_namestring
When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
prefixstring
The prefix, or title, to the party's name.
suffixstring
The suffix for the party's name.
surnamestring
When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
name_validation
name_validation
name_validation
name_validation
notification
additional_recipientsarray (contains the email_address object)
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_recipientsvalue associated with the invoice.notestring
A note to the payer.
send_to_invoicerboolean
Indicates whether to send a copy of the email to the merchant.
send_to_recipientboolean
Indicates whether to send a copy of the email to the recipient.
subjectstring
The subject of the email that is sent as a notification to the recipient.
partial_payment
allow_partial_paymentboolean
Indicates whether the invoice allows a partial payment. If
false, the invoice must be paid in full. Iftrue, the invoice allows partial payments.Note: This feature is not available for users in
India,Brazil, orIsrael.minimum_amount_dueThe minimum amount allowed for a partial payment. Valid only when
allow_partial_paymentistrue.
payment_detail
methodenum
required
The payment mode or method through which the invoicer can accept the payment.
The possible values are:
BANK_TRANSFER. Payments can be received through bank transfers.CASH. Payments can be received as cash.CHECK. Payments can be received as check.CREDIT_CARD. Payments can be received through credit card payments.DEBIT_CARD. Payments can be received through debit card payments.PAYPAL. Payments can be received through paypal payments.WIRE_TRANSFER. Payments can be received through wire transfer.OTHER. Payments can be received through other modes.
amountThe payment amount to record against the invoice. If you omit this parameter, the total invoice amount is marked as paid. This amount cannot exceed the amount due.
notestring
A note associated with an external cash or check payment.
payment_dateThe date when the invoice was paid, in Internet date and time format. For example, yyyy-MM-dd z.
payment_idstring
The ID for a PayPal payment transaction. Required for the
PAYPALpayment type.shipping_infoThe recipient's shipping information. Includes the user's contact information, which includes name and address.
typeenum
The payment type in an invoicing flow which can be PayPal or an external cash or check payment.
The possible values are:
PAYPAL. The payment type is PayPal.EXTERNAL. The payment type is an external cash or a check payment.
payment_method
payment_methodenum
The payment mode or method through which the invoicer can accept the payments.
The possible values are:
BANK_TRANSFER. Payments can be received through bank transfers.CASH. Payments can be received as cash.CHECK. Payments can be received as check.CREDIT_CARD. Payments can be received through credit card payments.DEBIT_CARD. Payments can be received through debit card payments.PAYPAL. Payments can be received through paypal payments.WIRE_TRANSFER. Payments can be received through wire transfer.OTHER. Payments can be received through other modes.
payment_reference
payment_idstring
The ID for the invoice payment.
payment_term
term_typeenum
The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.
The possible values are:
DUE_ON_RECEIPT. The payment for the invoice is due upon receipt of the invoice.DUE_ON_DATE_SPECIFIED. The payment for the invoice is due on the date specified in the invoice.NET_10. The payment for the invoice is due in 10 days.NET_15. The payment for the invoice is due in 15 days.NET_30. The payment for the invoice is due in 30 days.NET_45. The payment for the invoice is due in 45 days.NET_60. The payment for the invoice is due in 60 days.NET_90. The payment for the invoice is due in 90 days.NO_DUE_DATE. The invoice has no payment due date.
payment_term_type
payment_term_typeenum
The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.
The possible values are:
DUE_ON_RECEIPT. The payment for the invoice is due upon receipt of the invoice.DUE_ON_DATE_SPECIFIED. The payment for the invoice is due on the date specified in the invoice.NET_10. The payment for the invoice is due in 10 days.NET_15. The payment for the invoice is due in 15 days.NET_30. The payment for the invoice is due in 30 days.NET_45. The payment for the invoice is due in 45 days.NET_60. The payment for the invoice is due in 60 days.NET_90. The payment for the invoice is due in 90 days.NO_DUE_DATE. The invoice has no payment due date.
payment_type
payment_typeenum
The payment type. Can be PayPal or an external payment. Includes cash or a check.
The possible values are:
PAYPAL. The payment type is PayPal.EXTERNAL. The payment type is an external cash or a check payment.
payments
paid_amountThe aggregated payment amounts against this invoice.
transactionsarray (contains the payment_detail object)
An array of payment details for the invoice. The payment details of the invoice like payment type, method, date, discount and transaction type.
percentage
percentagestring
The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as
19.99.
phone
country_codestring
required
The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
national_numberstring
required
The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
extension_numberstring
The extension number.
phone
country_codestring
required
The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
national_numberstring
required
The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
extension_numberstring
The extension number.
phone_detail
country_codestring
required
The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
national_numberstring
required
The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
extension_numberstring
The extension number.
phone_typeThe phone type.
phone_type
phone_typeenum
The phone type.
phone_type
phone_typeenum
The phone type.
phone_with_type
The phone number, in its canonical international E.164 numbering plan format. Supports only the
national_numberproperty.phone_typeenum
The phone type.
phone_with_type.phone
national_numberstring
required
The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
qr_config
actionstring
The type of URL for which to generate a QR code. Valid values are
payanddetails.heightinteger
The height, in pixels, of the QR code image. Value is from
150to500.widthinteger
The width, in pixels, of the QR code image. Value is from
150to500.
refund_detail
methodenum
required
The payment mode or method through which the invoicer can accept the payments.
The possible values are:
BANK_TRANSFER. Payments can be received through bank transfers.CASH. Payments can be received as cash.CHECK. Payments can be received as check.CREDIT_CARD. Payments can be received through credit card payments.DEBIT_CARD. Payments can be received through debit card payments.PAYPAL. Payments can be received through paypal payments.WIRE_TRANSFER. Payments can be received through wire transfer.OTHER. Payments can be received through other modes.
amountThe amount to record as refunded. If you omit the amount, the total invoice paid amount is recorded as refunded.
refund_dateThe date when the invoice was refunded, in Internet date format. For example,
2014-02-27.refund_idstring
The ID for a PayPal payment transaction. Required for the
PAYPALpayment type.typeenum
The PayPal refund type. Indicates whether the refund was paid through PayPal or externally in the invoicing flow. The record refund method supports the
EXTERNALrefund type. ThePAYPALrefund type is supported for backward compatibility.The possible values are:
PAYPAL. The payment type is PayPal.EXTERNAL. The payment type is an external cash or a check payment.
refund_reference
refund_idstring
The ID of the refund of an invoice payment.
refunds
refund_amountThe aggregated refund amounts.
transactionsarray (contains the refund_detail object)
An array of refund details for the invoice. Includes the refund type, date, amount, and method.
search_data
archivedboolean
Indicates whether to list merchant-archived invoices in the response. Value is:
true. Response lists only merchant-archived invoices.false. Response lists only unarchived invoices.null. Response lists all invoices.
creation_date_rangeFilters the search by a creation date range for the invoice, in Internet date and time format.
currency_codeThe three-character ISO-4217 currency code that identifies the currency.
due_date_rangeFilters the search by a due date range for the invoice, in Internet date and time format.
fieldsarray (contains the field object)
A CSV file of fields to return for the user, if available. Because the invoice object can be very large, field filtering is required. Valid collection fields are
items,payments,refunds,additional_recipients_info, andattachments.invoice_date_rangeFilters the search by a date range for the invoice, in Internet date and time format.
invoice_numberstring
Filters the search by the invoice number.
memostring
A private bookkeeping memo for the user.
payment_date_rangeThe date and time range. Filters invoices by creation date, invoice date, due date, and payment date.
recipient_business_namestring
Filters the search by the recipient business name.
recipient_emailstring
Filters the search by the email address.
recipient_first_namestring
Filters the search by the recipient first name.
recipient_last_namestring
Filters the search by the recipient last name.
referencestring
The reference data, such as a PO number.
statusarray (contains the invoice_status object)
An array of status values.
total_amount_rangeFilters the search by the total amount.
tax_info
tax_idstring
required
The customer's tax ID value.
tax_id_typeenum
required
The customer's tax ID type.
The possible values are:
BR_CPF. The individual tax ID type, typically is 11 characters long.BR_CNPJ. The business tax ID type, typically is 14 characters long.
template
default_templateboolean
Indicates whether this template is the default template. A invoicer can have one default template.
idstring
The ID of the template.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
namestring
The template name.
Note: The template name must be unique.
settingsThe template settings. Describes which fields to show or hide when you create an invoice.
standard_templateboolean
Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.
template_infoThe template details. Includes invoicer business information, invoice recipients, items, and configuration.
unit_of_measureenum
The unit of measure for the template. Value is quantity, hours, or amount.
The possible values are:
QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.HOURS. The unit of measure is hours. This invoice template is typically used for services.AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.
template_configuration
allow_tipboolean
Indicates whether the invoice enables the customer to enter a tip amount during payment. If
true, the invoice shows a tip amount field so that the customer can enter a tip amount. Iffalse, the invoice does not show a tip amount field.Note: This feature is not available for users in
Hong Kong,Taiwan,India, orJapan.partial_paymentThe partial payment details. Includes the minimum amount that the invoicer wants the payer to pay.
tax_calculated_after_discountboolean
Indicates whether the tax is calculated before or after a discount. If
false, the tax is calculated before a discount. Iftrue, the tax is calculated after a discount.tax_inclusiveboolean
Indicates whether the unit price includes tax.
template_detail
The three-character ISO-4217 currency code that identifies the currency.
attachmentsarray (contains the file_reference object)
An array of PayPal IDs for the files that are attached to an invoice.
memostring
A private bookkeeping memo for the user.
notestring
A note to the invoice recipient. Also appears on the invoice notification email.
referencestring
The reference data. Includes a post office (PO) number.
terms_and_conditionsstring
The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.
template_display_preference
hiddenboolean
Indicates whether to show or hide this field.
template_info
additional_recipientsarray (contains the email_address object)
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_recipientsvalue associated with the invoice.amountThe invoice amount summary of the item total, discount, tax total, and shipping.
configurationThe template configuration details. Includes tax information, tip, and partial payment.
detailThe template-related details. Includes notes, terms and conditions, memo, and attachments.
due_amountThe amount due for the invoice.
invoicerThe invoicer information. Includes business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
itemsarray (contains the item object)
An array of invoice line-item information.
primary_recipientsarray (contains the recipient_info object)
The billing and shipping information. Includes name, email, address, phone, and language.
template_item_field
template_item_fieldenum
The field names for the invoice line items in the template.
The possible values are:
ITEMS_QUANTITY. The quantity of the item in the template that the invoicer provides to the payer. Value is from `-1000000` to `1000000`. Supports up to five decimal places.ITEMS_DESCRIPTION. The description of the item in the invoice template.ITEMS_DATE. The date in invoice template when the item or service was provided, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*.ITEMS_DISCOUNT. The item discount in the invoice template. Discount as a percent or amount at invoice level. Invoice discount amount is subtracted from the item total.ITEMS_TAX. The tax associated with the item in the invoice template. The tax amount is added to the item total. Value is from `0` to `100`. Supports up to five decimal places.
template_item_setting
display_preferenceThe display preference.
field_nameenum
The field name in
template_datafor which to map corresponding display preferences.The possible values are:
ITEMS_QUANTITY. The quantity of the item in the template that the invoicer provides to the payer. Value is from `-1000000` to `1000000`. Supports up to five decimal places.ITEMS_DESCRIPTION. The description of the item in the invoice template.ITEMS_DATE. The date in invoice template when the item or service was provided, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*.ITEMS_DISCOUNT. The item discount in the invoice template. Discount as a percent or amount at invoice level. Invoice discount amount is subtracted from the item total.ITEMS_TAX. The tax associated with the item in the invoice template. The tax amount is added to the item total. Value is from `0` to `100`. Supports up to five decimal places.
template_metadata
create_timeThe date and time when the resource was created, in Internet date and time format.
created_bystring
The email address of the account that created the resource.
last_update_timeThe date and time when the resource was last edited, in Internet date and time format.
last_updated_bystring
The email address of the account that last edited the resource.
template_settings
template_item_settingsarray (contains the template_item_setting object)
The template item headers display preference.
template_subtotal_settingsarray (contains the template_subtotal_setting object)
The template subtotal headers display preference.
template_subtotal_field
template_subtotal_fieldenum
The field names in the template for discount, shipping, and custom amounts.
The possible values are:
DISCOUNT. The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.SHIPPING. The shipping fee for all items in the invoice template. Also includes the tax on shipping.CUSTOM. The custom amount to apply to an invoice in the template. If you include a label, you must include the custom amount.
template_subtotal_setting
display_preferenceThe display preference.
field_nameenum
The field name in
template_datafor which to map corresponding display preferences.The possible values are:
DISCOUNT. The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.SHIPPING. The shipping fee for all items in the invoice template. Also includes the tax on shipping.CUSTOM. The custom amount to apply to an invoice in the template. If you include a label, you must include the custom amount.
templates
addressesarray (contains the address_portable object)
An array of addresses in the user's PayPal profile.
emailsAn array of emails in the user's PayPal profile.
linksarray (contains the link_description object)
An array of request-related HATEOAS links.
phonesarray (contains the phone_detail object)
An array of phone numbers in the user's PayPal profile.
templatesarray (contains the template object)
An array of details for each template. If
fieldsisnone, returns only the template name, ID, and default status.
unit_of_measure
unit_of_measureenum
The unit of measure for the invoiced item.
The possible values are:
QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.HOURS. The unit of measure is hours. This invoice template is typically used for services.AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.
Additional API information
Error messages
In addition to common HTTP status codes that the REST APIs return, the Invoices API can return the following errors.
INTERNAL_SERVER_ERRORAn internal server error occurred.
INVALID_REQUESTRequest is not well-formed, syntactically incorrect, or violates schema. Possible issues are
INVALID_STRING_MAX_LENGTH.Field value exceeded the maximum allowed number of characters.
INVALID_ARRAY_MAX_ITEMS.Only maximum of 100 email address is supported in additional recipients.
MISSING_REQUIRED_PARAMETER.Payment method is missing. Please pass a valid payment method.
INVALID_PAYMENT_METHOD.The value provided is not an acceptable method of payment.
NOT_SUPPORTED.Currency code is not supported.
INVALID_STRING_LENGTH.Currency code length should be 3 characters.
MISSING_REQUIRED_PARAMETER.Amount value is missing. Please provide a valid amount.
INVALID_PARAMETER_SYNTAX.Amount value is invalid. Should be a numeric value.
VALUE_CANNOT_BE_ZERO.Payment amount cannot be zero. Please provide a valid amount.
INVALID_DECIMAL_VALUE.Payment amount value is invalid. Can have non-negative value with maximum 7 digits and upto 2 fractions.
INVALID_INTEGER_VALUE.Payment amount value is invalid. Can have non-negative value with maximum 6 digits.
INVALID_PARAMETER_SYNTAX.Date should be of format yyyy-mm-dd.
INVALID_REFUND_METHOD.The value provided is not an acceptable method of refund.
INVALID_INTEGER_MAX_VALUE.Value exceeds max value.
INVALID_INTEGER_MIN_VALUE.Value less than minimum value.
TEMPLATE_NAME_ALREADY_EXISTS.Template name already exists.
NOT_AUTHORIZEDAuthorization failed due to insufficient permissions. Possible issues are
PERMISSION_DENIED.The requested invoice cannot be fetched due to insufficient permissions.
CANNOT_DELETE_GLOBAL_TEMPLATE.Global templates cannot be deleted.
RESOURCE_NOT_FOUNDThe specified resource does not exist.
UNPROCESSABLE_ENTITYThe requested action could not be performed, semantically incorrect, or failed business validation. Possible issues are
INVOICE_ALREADY_SENT.The Invoice is already sent.
CANNOT_SEND_INVOICE.Only DRAFT and UNPAID invoices can be sent.
INVOICE_ALREADY_SHARED.Invoice has already been shared via link.
MISSING_RECIPIENT_EMAIL.Missing recipient email address. Recipient email address is required to send invoice via PayPal.
INVALID_SCHEDULE_DATE.Invoice can only be scheduled for a future date no later than 365 days from today's date.
CANNOT_CANCEL_DRAFT_INVOICE.Draft invoice cannot be canceled.
CANNOT_CANCEL_PAID_INVOICE.Cannot cancel a paid or partially paid invoice.
CANNOT_CANCEL_REFUNDED_INVOICE.Cannot cancel a refunded or partially refunded invoice.
CANNOT_CANCEL_SCHEDULED_INVOICE.Cannot cancel a scheduled invoice.
INVOICE_CANCELED_ALREADY.Invoice is already cancelled.
PAYMENT_AMOUNT_GREATER_THAN_AMOUNT_DUE.Payment amount is greater than the amount due.
INVALID_INVOICE_TYPE.The invoice type is not valid for paying an invoice.
INVALID_INVOICE_STATE.Current invoice state does not support payment processing.
INVALID_REFUND_AMOUNT.Recorded refunds cannot exceed recorded payments.
CANNOT_PROCESS_REFUNDS.Current invoice state does not support refunds.
INVOICE_CANNOT_BE_DELETED.Only invoices in draft, scheduled, or canceled status can be deleted.
CANNOT_DELETE_EXTERNAL_PAYMENT.The external payment cannot be deleted as the recorded refund cannot exceed the recored payment for an invoice.
CANNOT_REMIND_DRAFT_INVOICE.You cannot remind an invoice which is in DRAFT status. Only UNPAID, SENT and PARTIALLY_PAID invoices can be reminded.
USER_NOT_FOUND.User is not associated with paypal based on invoicer email.