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_number
string
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
page
integer
The page number to be retrieved, for the list of items. So, a combination of
page=1
andpage_size=20
returns the first 20 invoices. A combination ofpage=2
andpage_size=20
returns the next 20 invoices.page_size
integer
The maximum number of invoices to return in the response.
total_required
boolean
Indicates whether the to show
total_pages
andtotal_items
in the response.fields
string
A comma-separated list of additional fields to return, if available.
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.total_pages
integer
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
total_items
integer
The total number of invoices that match the search criteria.
Note: Clients MUST NOT assume that the value of
total_items
is constant. The value MAY change from one request to the next.items
array (contains the invoice object)
The list of invoices that match the search criteria.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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
id
string
The ID of the invoice.
parent_id
string
The parent ID to an invoice that defines the group invoice to which the invoice is related.
status
enum
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.
The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.
invoicer
The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
primary_recipients
array (contains the recipient_info object)
The billing and shipping information. Includes name, email, address, phone and language.
additional_recipients
array (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_recipients
value associated with the invoice.items
array (contains the item object)
An array of invoice line item information.
configuration
The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
amount
The invoice amount summary of item total, discount, tax total and shipping..
due_amount
The due amount, which is the balance amount outstanding after payments.
gratuity
The amount paid by the payer as gratuity to the invoicer.
payments
List of payments registered against the invoice..
refunds
List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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 and a JSON response body that shows invoice details.href
string
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. Thehref
is the key HATEOAS component that links a completed call with a subsequent call.rel
string
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
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_id
string
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 content
Fully update invoice
invoice
object. This call does not support partial updates.Query parameters
send_to_recipient
boolean
Indicates whether to send the invoice update notification to the recipient.
send_to_invoicer
boolean
Indicates whether to send the invoice update notification to the merchant.
Path parameters
invoice_id
string
required
The ID of the invoice to update.
Request body
id
string
The ID of the invoice.
parent_id
string
The parent ID to an invoice that defines the group invoice to which the invoice is related.
status
enum
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.
The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.
invoicer
The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
primary_recipients
array (contains the recipient_info object)
The billing and shipping information. Includes name, email, address, phone and language.
additional_recipients
array (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_recipients
value associated with the invoice.items
array (contains the item object)
An array of invoice line item information.
configuration
The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
amount
The invoice amount summary of item total, discount, tax total and shipping..
due_amount
The due amount, which is the balance amount outstanding after payments.
gratuity
The amount paid by the payer as gratuity to the invoicer.
payments
List of payments registered against the invoice..
refunds
List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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
204 No Content
status code with no JSON response body.id
string
The ID of the invoice.
parent_id
string
The parent ID to an invoice that defines the group invoice to which the invoice is related.
status
enum
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.
detail
The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.
invoicer
The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
primary_recipients
array (contains the recipient_info object)
The billing and shipping information. Includes name, email, address, phone and language.
additional_recipients
array (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_recipients
value associated with the invoice.items
array (contains the item object)
An array of invoice line item information.
configuration
The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
amount
The invoice amount summary of item total, discount, tax total and shipping..
due_amount
The due amount, which is the balance amount outstanding after payments.
gratuity
The amount paid by the payer as gratuity to the invoicer.
payments
List of payments registered against the invoice..
refunds
List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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_id
string
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.id
string
The ID of the invoice.
parent_id
string
The parent ID to an invoice that defines the group invoice to which the invoice is related.
status
enum
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.
detail
The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.
invoicer
The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
primary_recipients
array (contains the recipient_info object)
The billing and shipping information. Includes name, email, address, phone and language.
additional_recipients
array (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_recipients
value associated with the invoice.items
array (contains the item object)
An array of invoice line item information.
configuration
The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
amount
The invoice amount summary of item total, discount, tax total and shipping..
due_amount
The due amount, which is the balance amount outstanding after payments.
gratuity
The amount paid by the payer as gratuity to the invoicer.
payments
List of payments registered against the invoice..
refunds
List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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_id
string
required
The ID of the invoice to cancel.
Request body
subject
string
The subject of the email that is sent as a notification to the recipient.
note
string
A note to the payer.
send_to_invoicer
boolean
Indicates whether to send a copy of the email to the merchant.
send_to_recipient
boolean
Indicates whether to send a copy of the email to the recipient.
additional_recipients
array (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_recipients
value associated with the invoice.
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 Content
Generate QR code
Path parameters
invoice_id
string
required
The ID of the invoice for which to generate a QR code.
Request body
width
integer
The width, in pixels, of the QR code image. Value is from
150
to500
.height
integer
The height, in pixels, of the QR code image. Value is from
150
to500
.action
string
The type of URL for which to generate a QR code. Valid values are
pay
anddetails
.
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_id
string
required
The ID of the invoice to mark as paid.
Request body
type
enum
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_id
string
The ID for a PayPal payment transaction. Required for the
PAYPAL
payment type.payment_date
The date when the invoice was paid, in Internet date and time format. For example, yyyy-MM-dd z.
method
enum
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.
note
string
A note associated with an external cash or check payment.
amount
The 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.
shipping_info
The recipient's shipping information. Includes the user's contact information, which includes name and address.
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_id
string
The ID for the invoice payment.
Sample Response
{
"payment_id": "EXTR-86F38350LX4353815"
}
Delete external payment
Path parameters
invoice_id
string
required
The ID of the invoice from which to delete an external payment transaction.
transaction_id
string
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 Content
Record refund for invoice
REFUNDED
. Otherwise, the invoice is marked as PARTIALLY REFUNDED
.Path parameters
invoice_id
string
required
The ID of the invoice to mark as refunded.
Request body
type
enum
The PayPal refund type. Indicates whether the refund was paid through PayPal or externally in the invoicing flow. The record refund method supports the
EXTERNAL
refund type. ThePAYPAL
refund 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_id
string
The ID for a PayPal payment transaction. Required for the
PAYPAL
payment type.refund_date
The date when the invoice was refunded, in Internet date format. For example,
2014-02-27
.amount
The amount to record as refunded. If you omit the amount, the total invoice paid amount is recorded as refunded.
method
enum
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.
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_id
string
The ID of the refund of an invoice payment.
Sample Response
{
"refund_id": "EXTR-2LG703375E477444T"
}
Delete external refund
Path parameters
invoice_id
string
required
The ID of the invoice from which to delete the external refund transaction.
transaction_id
string
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 Content
Send invoice reminder
notification
object that defines the subject of the reminder and other details.Path parameters
invoice_id
string
required
The ID of the invoice for which to send a reminder.
Request body
subject
string
The subject of the email that is sent as a notification to the recipient.
note
string
A note to the payer.
send_to_invoicer
boolean
Indicates whether to send a copy of the email to the merchant.
send_to_recipient
boolean
Indicates whether to send a copy of the email to the recipient.
additional_recipients
array (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_recipients
value associated with the invoice.
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 Content
Send 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_recipient
body parameter totrue
.
Path parameters
invoice_id
string
required
The ID of the invoice to send.
Request body
subject
string
The subject of the email that is sent as a notification to the recipient.
note
string
A note to the payer.
send_to_invoicer
boolean
Indicates whether to send a copy of the email to the merchant.
send_to_recipient
boolean
Indicates whether to send a copy of the email to the recipient.
additional_recipients
array (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_recipients
value associated with the invoice.
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.links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
202 Accepted
Search invoices (resource group)
Use the /search-invoices
resource to search for and list invoices that match search criteria.
Search for invoices
Query parameters
page
integer
The page number to be retrieved, for the list of items. So, a combination of
page=1
andpage_size=20
returns the first 20 invoices. A combination ofpage=2
andpage_size=20
returns the next 20 invoices.page_size
integer
The page size for the search results.
total_required
boolean
Indicates whether the to show
total_pages
andtotal_items
in the response.
Request body
recipient_email
string
Filters the search by the email address.
recipient_first_name
string
Filters the search by the recipient first name.
recipient_last_name
string
Filters the search by the recipient last name.
recipient_business_name
string
Filters the search by the recipient business name.
invoice_number
string
Filters the search by the invoice number.
status
array (contains the invoice_status object)
An array of status values.
reference
string
The reference data, such as a PO number.
currency_code
The three-character ISO-4217 currency code that identifies the currency.
memo
string
A private bookkeeping memo for the user.
total_amount_range
Filters the search by the total amount.
invoice_date_range
Filters the search by a date range for the invoice, in Internet date and time format.
due_date_range
Filters the search by a due date range for the invoice, in Internet date and time format.
payment_date_range
The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.
creation_date_range
Filters the search by a creation date range for the invoice, in Internet date and time format.
archived
boolean
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.
fields
array (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
.
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.total_pages
integer
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
total_items
integer
The total number of invoices that match the search criteria.
Note: Clients MUST NOT assume that the value of
total_items
is constant. The value MAY change from one request to the next.items
array (contains the invoice object)
The list of invoices that match the search criteria.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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
fields
string
The fields to return in the response. Value is
all
ornone
. To return only the template name, ID, and default attributes, specifynone
.page
integer
The page number to be retrieved, for the list of templates. So, a combination of
page=1
andpage_size=20
returns the first 20 templates. A combination ofpage=2
andpage_size=20
returns the next 20 templates.page_size
integer
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.addresses
array (contains the address_portable object)
An array of addresses in the user's PayPal profile.
emails
An array of emails in the user's PayPal profile.
phones
array (contains the phone_detail object)
An array of phone numbers in the user's PayPal profile.
templates
array (contains the template object)
An array of details for each template. If
fields
isnone
, returns only the template name, ID, and default status.links
array (contains the link_description object)
An array of request-related HATEOAS links.
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
id
string
The ID of the template.
name
string
The template name.
Note: The template name must be unique.
default_template
boolean
Indicates whether this template is the default template. A invoicer can have one default template.
template_info
The template details. Includes invoicer business information, invoice recipients, items, and configuration.
settings
The template settings. Describes which fields to show or hide when you create an invoice.
unit_of_measure
enum
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.
standard_template
boolean
Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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
200 OK
status code and a JSON response body that shows template details if you set prefer=return=representation
.href
string
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. Thehref
is the key HATEOAS component that links a completed call with a subsequent call.rel
string
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
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_id
string
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 Content
Fully update template
template
object. This call does not support partial updates.Path parameters
template_id
string
required
The ID of the template for which to show details.
Request body
id
string
The ID of the template.
name
string
The template name.
Note: The template name must be unique.
default_template
boolean
Indicates whether this template is the default template. A invoicer can have one default template.
template_info
The template details. Includes invoicer business information, invoice recipients, items, and configuration.
settings
The template settings. Describes which fields to show or hide when you create an invoice.
unit_of_measure
enum
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.
standard_template
boolean
Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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
204 No Content
status code with no JSON response body.id
string
The ID of the template.
name
string
The template name.
Note: The template name must be unique.
default_template
boolean
Indicates whether this template is the default template. A invoicer can have one default template.
template_info
The template details. Includes invoicer business information, invoice recipients, items, and configuration.
settings
The template settings. Describes which fields to show or hide when you create an invoice.
unit_of_measure
enum
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.
standard_template
boolean
Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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_id
string
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.id
string
The ID of the template.
name
string
The template name.
Note: The template name must be unique.
default_template
boolean
Indicates whether this template is the default template. A invoicer can have one default template.
template_info
The template details. Includes invoicer business information, invoice recipients, items, and configuration.
settings
The template settings. Describes which fields to show or hide when you create an invoice.
unit_of_measure
enum
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.
standard_template
boolean
Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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
links
array (contains the link_description object)
An array of request-related HATEOAS links.
address_details
street_number
string
The street number.
street_name
string
The street name. Just
Drury
inDrury Lane
.street_type
string
The street type. For example, avenue, boulevard, road, or expressway.
delivery_service
string
The delivery service. Post office box, bag number, or post office name.
building_name
string
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
.sub_building
string
The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
address_portable
address_line_1
string
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_2
string
The second line of the address. For example, suite or apartment number.
address_line_3
string
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_4
string
The neighborhood, ward, or district. Smaller than
admin_area_level_3
orsub_locality
. Value is:- The postal sorting code for Guernsey and many French territories, such as French Guiana.
- The fine-grained administrative levels in China.
admin_area_3
string
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_2
string
A city, town, or village. Smaller than
admin_area_level_1
.admin_area_1
string
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,
CA
and notCalifornia
. Value, by country, is:- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
postal_code
string
The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.address_details
The 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_1
is usually a combination ofaddress_details.street_number
,street_name
, andstreet_type
.
address_portable_postal_code_validation
address_portable_postal_code_validation
amount_summary_detail
currency_code
The three-character ISO-4217 currency code that identifies the currency.
value
string
The value, which might be:
- An integer for currencies like
JPY
that are not typically fractional. - A decimal fraction for currencies like
TND
that are subdivided into thousandths.
- An integer for currencies like
breakdown
The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, custom amount, shipping and discounts, if any.
amount_with_breakdown
item_total
The subtotal for all items. Must equal the sum of (
items[].unit_amount
*items[].quantity
) for all items.discount
The 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.
tax_total
The aggregated amount of the item and shipping taxes.
shipping
The shipping fee for all items. Includes tax on shipping.
custom
The custom amount to apply to an invoice. If you include a label, you must include the custom amount.
billing_info
email_address
The invoice recipient email address. If you omit this value, the invoice is payable and a notification email is not sent.
phones
array (contains the phone_detail object)
The invoice recipient's phone numbers. Extension number is not supported.
additional_info
string
Any additional information about the recipient.
language
The 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.
business_name
business_name
string
Required. The business name of the party.
business_name_validation
business_name_validation
configuration
tax_calculated_after_discount
boolean
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_inclusive
boolean
Indicates whether the unit price includes tax.
allow_tip
boolean
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_payment
The partial payment details. Includes the minimum amount that the invoicer wants the payer to pay.
template_id
string
The template ID. The template determines the layout of the invoice. Includes which fields to show and hide.
country_code
country_code
string
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
currency_code
currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
custom_amount
label
string
required
The label to the custom amount of the invoice.
amount
The custom amount value. Value is from
-1000000
to1000000
. Supports up to two decimal places.
date_no_time
date_no_time
string
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_time
type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
date_time
date_time
string
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 start date of the range. Filters invoices by creation date, invoice date, due date, and payment date.
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})$
detail
reference
string
The reference data. Includes a post office (PO) number.
The three-character ISO-4217 currency code that identifies the currency.
note
string
A note to the invoice recipient. Also appears on the invoice notification email.
terms_and_conditions
string
The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.
memo
string
A private bookkeeping memo for the user.
attachments
array (contains the file_reference object)
An array of PayPal IDs for the files that are attached to an invoice.
email_address
email_address
string
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
name
string
required
The human-readable, unique name of the error.
message
string
required
The message that describes the error.
debug_id
string
required
The PayPal internal ID. Used for correlation purposes.
information_link
string
The information link, or URI, that shows detailed information about this error for the developer.
details
array (contains the error_details object)
An array of additional details about the error.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
error_details
field
string
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.
value
string
The value of the field that caused the error.
location
string
The location of the field that caused the error. Value is
body
,path
, orquery
.issue
string
required
The unique, fine-grained application-level error code.
description
string
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.
field
field
string
The name of the field.
file_reference
id
string
The ID of the referenced file.
reference_url
string
The reference URL for the file.
content_type
string
create_time
The date and time when the file was created, in Internet date and time format.
size
string
The size of the file, in bytes.
invoice
id
string
The ID of the invoice.
parent_id
string
The parent ID to an invoice that defines the group invoice to which the invoice is related.
status
enum
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.
The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.
invoicer
The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
primary_recipients
array (contains the recipient_info object)
The billing and shipping information. Includes name, email, address, phone and language.
additional_recipients
array (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_recipients
value associated with the invoice.items
array (contains the item object)
An array of invoice line item information.
configuration
The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
amount
The invoice amount summary of item total, discount, tax total and shipping..
due_amount
The due amount, which is the balance amount outstanding after payments.
gratuity
The amount paid by the payer as gratuity to the invoicer.
payments
List of payments registered against the invoice..
refunds
List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
invoice_creation_flow
invoice_creation_flow
enum
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
reference
string
The reference data. Includes a post office (PO) number.
The three-character ISO-4217 currency code that identifies the currency.
note
string
A note to the invoice recipient. Also appears on the invoice notification email.
terms_and_conditions
string
The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.
memo
string
A private bookkeeping memo for the user.
attachments
array (contains the file_reference object)
An array of PayPal IDs for the files that are attached to an invoice.
invoice_number
string
The invoice number. Default is the number that is auto-incremented number from the last number.
invoice_date
The invoice date as specificed by the sender, in Internet date and time format. Only UTC is supported in response. For example, yyyy-MM-ddTz.
payment_term
The payment due date for the invoice. Value is either but not both
term_type
ordue_date
.metadata
The audit metadata. Captures all invoicing actions on create, send, update, and cancel.
invoice_number
invoice_number
string
The invoice number. If you omit this value, the default is the auto-incremented number from the last number.
invoice_payment_term
term_type
The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.
due_date
The date when the invoice payment is due, in Internet date and time format. For example, yyyy-MM-ddTz.
invoice_status
invoice_status
enum
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
email_address
The 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.
phones
array (contains the phone_detail object)
An array of invoicer's phone numbers. The invoicer can choose to hide the phone number on the invoice.
website
string
The invoicer's website.
tax_id
string
The invoicer's tax ID.
additional_notes
string
Any additional information. Includes business hours.
logo_url
string
The full URL to an external logo image. The logo image must not be larger than 250 pixels wide by 90 pixels high.
invoices
total_pages
integer
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
total_items
integer
The total number of invoices that match the search criteria.
Note: Clients MUST NOT assume that the value of
total_items
is constant. The value MAY change from one request to the next.items
array (contains the invoice object)
The list of invoices that match the search criteria.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
item
id
string
The ID of the invoice line item.
name
string
required
The item name for the invoice line item.
description
string
The item description for the invoice line item.
quantity
string
required
The quantity of the item that the invoicer provides to the payer. Value is from
-1000000
to1000000
. Supports up to five decimal places.The unit price of the item. This does not include tax and discount. Value is from
-1000000
to1000000
. Supports up to two decimal places.tax
The tax associated with the item. The tax amount is added to the item total. Value is from
0
to100
. Supports up to five decimal places.item_date
The date when the item or service was provided, in Internet date and time format. For example, yyyy-MM-ddTz.
discount
Discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.
unit_of_measure
enum
The unit of measure for the invoiced item. For
AMOUNT
theunit_amount
andquantity
are not shown on the invoice.Note: If your specify different
unit_of_measure
values 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
language
string
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
href
string
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. Thehref
is the key HATEOAS component that links a completed call with a subsequent call.rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
metadata
create_time
The date and time when the resource was created, in Internet date and time format.
created_by
string
The email address of the account that created the resource.
last_update_time
The date and time when the resource was last edited, in Internet date and time format.
last_updated_by
string
The email address of the account that last edited the resource.
cancel_time
The date and time when the resource was canceled, in Internet date and time format.
cancelled_by
string
The actor who canceled the resource.
first_sent_time
The date and time when the resource was first sent, in Internet date and time format.
last_sent_time
The date and time when the resource was last sent, in Internet date and time format.
last_sent_by
string
The email address of the account that last sent the resource.
created_by_flow
The flow variation that created this invoice.
recipient_view_url
string
The URL for the invoice payer view hosted on paypal.com.
invoicer_view_url
string
The URL for the invoice merchant view hosted on paypal.com.
money
The three-character ISO-4217 currency code that identifies the currency.
value
string
required
The value, which might be:
- An integer for currencies like
JPY
that are not typically fractional. - A decimal fraction for currencies like
TND
that are subdivided into thousandths.
- An integer for currencies like
name
prefix
string
The prefix, or title, to the party's name.
given_name
string
When the party is a person, the party's given, or first, name.
surname
string
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.
middle_name
string
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.
suffix
string
The suffix for the party's name.
alternate_full_name
string
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_name
string
When the party is a person, the party's full name.
name_validation
name_validation
notification
subject
string
The subject of the email that is sent as a notification to the recipient.
note
string
A note to the payer.
send_to_invoicer
boolean
Indicates whether to send a copy of the email to the merchant.
send_to_recipient
boolean
Indicates whether to send a copy of the email to the recipient.
additional_recipients
array (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_recipients
value associated with the invoice.
partial_payment
allow_partial_payment
boolean
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_due
The minimum amount allowed for a partial payment. Valid only when
allow_partial_payment
istrue
.
payment_detail
type
enum
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_id
string
The ID for a PayPal payment transaction. Required for the
PAYPAL
payment type.payment_date
The date when the invoice was paid, in Internet date and time format. For example, yyyy-MM-dd z.
method
enum
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.
note
string
A note associated with an external cash or check payment.
amount
The 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.
shipping_info
The recipient's shipping information. Includes the user's contact information, which includes name and address.
payment_method
payment_method
enum
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_id
string
The ID for the invoice payment.
payment_term
term_type
enum
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_type
enum
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_type
enum
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_amount
The aggregated payment amounts against this invoice.
transactions
array (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
percentage
string
The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as
19.99
.
phone
country_code
string
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_number
string
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_number
string
The extension number.
phone_detail
country_code
string
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_number
string
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_number
string
The extension number.
phone_type
The phone type.
phone_type
phone_type
enum
The phone type.
qr_config
width
integer
The width, in pixels, of the QR code image. Value is from
150
to500
.height
integer
The height, in pixels, of the QR code image. Value is from
150
to500
.action
string
The type of URL for which to generate a QR code. Valid values are
pay
anddetails
.
refund_detail
type
enum
The PayPal refund type. Indicates whether the refund was paid through PayPal or externally in the invoicing flow. The record refund method supports the
EXTERNAL
refund type. ThePAYPAL
refund 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_id
string
The ID for a PayPal payment transaction. Required for the
PAYPAL
payment type.refund_date
The date when the invoice was refunded, in Internet date format. For example,
2014-02-27
.amount
The amount to record as refunded. If you omit the amount, the total invoice paid amount is recorded as refunded.
method
enum
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.
refund_reference
refund_id
string
The ID of the refund of an invoice payment.
refunds
refund_amount
The aggregated refund amounts.
transactions
array (contains the refund_detail object)
An array of refund details for the invoice. Includes the refund type, date, amount, and method.
search_data
recipient_email
string
Filters the search by the email address.
recipient_first_name
string
Filters the search by the recipient first name.
recipient_last_name
string
Filters the search by the recipient last name.
recipient_business_name
string
Filters the search by the recipient business name.
invoice_number
string
Filters the search by the invoice number.
status
array (contains the invoice_status object)
An array of status values.
reference
string
The reference data, such as a PO number.
currency_code
The three-character ISO-4217 currency code that identifies the currency.
memo
string
A private bookkeeping memo for the user.
total_amount_range
Filters the search by the total amount.
invoice_date_range
Filters the search by a date range for the invoice, in Internet date and time format.
due_date_range
Filters the search by a due date range for the invoice, in Internet date and time format.
payment_date_range
The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.
creation_date_range
Filters the search by a creation date range for the invoice, in Internet date and time format.
archived
boolean
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.
fields
array (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
.
template
id
string
The ID of the template.
name
string
The template name.
Note: The template name must be unique.
default_template
boolean
Indicates whether this template is the default template. A invoicer can have one default template.
template_info
The template details. Includes invoicer business information, invoice recipients, items, and configuration.
settings
The template settings. Describes which fields to show or hide when you create an invoice.
unit_of_measure
enum
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.
standard_template
boolean
Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
template_configuration
tax_calculated_after_discount
boolean
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_inclusive
boolean
Indicates whether the unit price includes tax.
allow_tip
boolean
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_payment
The partial payment details. Includes the minimum amount that the invoicer wants the payer to pay.
template_detail
reference
string
The reference data. Includes a post office (PO) number.
The three-character ISO-4217 currency code that identifies the currency.
note
string
A note to the invoice recipient. Also appears on the invoice notification email.
terms_and_conditions
string
The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.
memo
string
A private bookkeeping memo for the user.
attachments
array (contains the file_reference object)
An array of PayPal IDs for the files that are attached to an invoice.
template_display_preference
hidden
boolean
Indicates whether to show or hide this field.
template_info
detail
The template-related details. Includes notes, terms and conditions, memo, and attachments.
invoicer
The invoicer information. Includes business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
primary_recipients
array (contains the recipient_info object)
The billing and shipping information. Includes name, email, address, phone, and language.
additional_recipients
array (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_recipients
value associated with the invoice.items
array (contains the item object)
An array of invoice line-item information.
configuration
The template configuration details. Includes tax information, tip, and partial payment.
amount
The invoice amount summary of the item total, discount, tax total, and shipping.
due_amount
The amount due for the invoice.
template_item_field
template_item_field
enum
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
field_name
enum
The field name in
template_data
for 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.
display_preference
The display preference.
template_metadata
create_time
The date and time when the resource was created, in Internet date and time format.
created_by
string
The email address of the account that created the resource.
last_update_time
The date and time when the resource was last edited, in Internet date and time format.
last_updated_by
string
The email address of the account that last edited the resource.
template_settings
template_item_settings
array (contains the template_item_setting object)
The template item headers display preference.
template_subtotal_settings
array (contains the template_subtotal_setting object)
The template subtotal headers display preference.
template_subtotal_field
template_subtotal_field
enum
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
field_name
enum
The field name in
template_data
for 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.
display_preference
The display preference.
templates
addresses
array (contains the address_portable object)
An array of addresses in the user's PayPal profile.
emails
An array of emails in the user's PayPal profile.
phones
array (contains the phone_detail object)
An array of phone numbers in the user's PayPal profile.
templates
array (contains the template object)
An array of details for each template. If
fields
isnone
, returns only the template name, ID, and default status.links
array (contains the link_description object)
An array of request-related HATEOAS links.
unit_of_measure
unit_of_measure
enum
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.