Invoicing(1)

API Version v1

?This API is currently not supported by our SDK

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

operation/invoice.create Create draft invoice

post/v1/invoicing/invoices

Try it

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

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

SecurityOauth2

Request

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


number	string<= 25 characters The invoice number. If you omit this value, the default is the number that the API automatically increments from the last number.
billing_info	Array of objects (billing_info) = 1 items An array of billing information for the invoice recipient. > Note: This value is an array with only one element.
cc_info	Array of objects (Participant) An array of email addresses to which PayPal sends a copy of the invoice.
items	Array of objects (invoice_item) <= 100 items An array of invoice line item information.
invoice_date	string<date> The invoice date as specified by the sender, in Internet date and time format.
reference	string<= 60 characters The reference data, such as PO number.
allow_partial_payment	boolean Default:false Indicates whether the invoice allows a partial payment. If `false`, the invoice must be paid in full. If `true`, the invoice allows partial payments. > Note: This feature is not available for merchants in `India`, `Brazil`, or `Israel`.
tax_calculated_after_discount	boolean Default:false Indicates whether the tax is calculated before or after a discount. If `false`, the tax is calculated before a discount. If `true`, the tax is calculated after a discount.
tax_inclusive	boolean Default:false Indicates whether the unit price includes tax.
terms	string<= 4000 characters The general terms of the invoice.
note	string<= 4000 characters A note to the invoice recipient. The note also appears on the invoice notification email.
merchant_memo	string<= 500 characters A private bookkeeping memo for the merchant.
logo_url	string<uri><= 4000 characters The full URL to an external logo image. The logo must not be larger than 250 pixels wide by 90 pixels high. The logo must be stored on a secure server.
allow_tip	boolean Default:false 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. If `false`, the invoice does not show a tip amount field. > Note: This feature is not available for merchants in `Hong Kong`, `Taiwan`, `India`, or `Japan`.
template_id	string Default:"PayPal system template" This value is only used to determine the layout to display on the create or edit invoice experience, such as which fields to show and hide. It does not impact the view of the invoice that the customer receives. > Note: If you are just using the Invoicing APIs to create and send invoices, leave this field blank. The `template_id` is only needed if you use the Invoicing API to build a full invoicing solution that includes templates.
merchant_info required	object (merchant_info) The merchant business information that appears on the invoice.
shipping_info	object (shipping_info) The shipping information for the invoice recipient.
payment_term	object (payment_term) The payment term of the invoice. If you specify `term_type`, you cannot specify `due_date`, and vice versa.
discount	object (Discount) The discount as a percent or an amount value. For example, to specify 10%, enter `10`. Alternatively, to specify an amount of 5, enter `5`.
shipping_cost	object (shipping_cost) The shipping cost, as a percent or amount value.
custom	object (custom_amount) The custom amount to apply to an invoice. If you include a label, you must include a custom amount.
minimum_amount_due	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Responses

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

Request samples

Payload
cURL
Node.js
Java
Python

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

Sample 1 - 201 - Create InvoiceSample 1 - 201 - Create Invoice

Copy

Expand allCollapse all

`{"merchant_info": {"email": "merchant@example.com",

"first_name": "David",

"last_name": "Larusso",

"business_name": "Mitchell & Murray",

"phone": {"country_code": "001",

"national_number": "4085551234"

"address": {"line1": "1234 First Street",

"city": "Anytown",

"state": "CA",

"postal_code": "98765",

"country_code": "US"

}

"billing_info": [{"email": "bill-me@example.com",

"first_name": "Stephanie",

"last_name": "Meyers"

}

],

"shipping_info": {"first_name": "Stephanie",

"last_name": "Meyers",

"address": {"line1": "1234 Main Street",

"city": "Anytown",

"state": "CA",

"postal_code": "98765",

"country_code": "US"

}

"items": [{"name": "Zoom System wireless headphones",

"quantity": 2,

"unit_price": {"currency": "USD",

"value": "120"

},

"tax": {"name": "Tax",

"percent": 8

}

},

{"name": "Bluetooth speaker",

"quantity": 1,

"unit_price": {"currency": "USD",

"value": "145"

},

"tax": {"name": "Tax",

"percent": 8

}

}

],

"discount": {"percent": 1

"shipping_cost": {"amount": {"currency": "USD",

"value": "10"

}

"note": "Thank you for your business.",

"terms": "No refunds after 30 days."

Response samples

application/json

Sample 1 - 201 - Create InvoiceSample 1 - 201 - Create Invoice

Copy

Expand allCollapse all

`{"id": "INV2-RUVR-ADWQ-H89Y-ABCD",

"number": "INV 01256",

"status": "DRAFT",

"merchant_info": {"email": "merchant@example.com",

"first_name": "David",

"last_name": "Larusso",

"business_name": "Mitchell & Murray",

"phone": {"country_code": "001",

"national_number": "4085551234"

"address": {"line1": "1234 First Street",

"city": "Anytown",

"state": "CA",

"postal_code": "98765",

"country_code": "US"

}

"billing_info": [{"email": "bill-me@example.com",

"first_name": "Stephanie",

"last_name": "Meyers"

}

],

"shipping_info": {"first_name": "Stephanie",

"last_name": "Meyers",

"address": {"line1": "1234 Main Street",

"city": "Anytown",

"state": "CA",

"postal_code": "98765",

"country_code": "US"

}

"items": [{"name": "Zoom System wireless headphones",

"quantity": 2,

"unit_price": {"currency": "USD",

"value": "120.00"

},

"tax": {"name": "Tax",

"percent": 8,

"amount": {"currency": "USD",

"value": "19.20"

}

}

},

{"name": "Bluetooth speaker",

"quantity": 1,

"unit_price": {"currency": "USD",

"value": "145.00"

},

"tax": {"name": "Tax",

"percent": 8,

"amount": {"currency": "USD",

"value": "11.60"

}

}

}

],

"invoice_date": "2017-06-22 PDT",

"discount": {"percent": 10,

"amount": {"currency": "USD",

"value": "38.50"

}

"shipping_cost": {"amount": {"currency": "USD",

"value": "10.00"

}

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"note": "Thank you for your business.",

"total_amount": {"currency": "USD",

"value": "387.30"

"metadata": {"created_date": "2017-06-22 09:39:04 PDT"

"allow_tip": false,

"links": [{"rel": "self",

"href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX",

"method": "GET"

},

{"rel": "send",

"href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX/send",

"method": "POST"

},

{"rel": "update",

"href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX",

"method": "PUT"

},

{"rel": "delete",

"href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX",

"method": "DELETE"

}

]

operation/invoice.get_all List invoices

get/v1/invoicing/invoices

Try it

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

SecurityOauth2

Request

query Parameters


page	integer Default:1 The zero-relative start index of the entire list of merchant invoices that are returned in the response. So, the combination of `page=0` and `page_size=20` returns the first 20 invoices. The combination of `page=20` and `page_size=20` returns the next 20 invoices.
page_size	integer Default:20 The number of invoices to return in the response.
total_count_required	boolean Default:false Indicates whether to show the total count in the response.

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

any

Responses

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

Request samples

Payload
cURL
Node.js
Java
Python

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

Copy

{ }

Response samples

application/json

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

Copy

Expand allCollapse all

`{"total_count": 589,

"invoices": [{"id": "INV2-2NB5-UJ7A-YSUJ-ABCD",

"number": "9879878979003791",

"status": "DRAFT",

"merchant_info": {"email": "merchant@example.com"

},

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

}

],

"shipping_info": {"first_name": "Sally",

"last_name": "Patient",

"business_name": "Not applicable"

},

"invoice_date": "2014-02-27 PST",

"note": "Medical Invoice 16 Jul, 2013 PST",

"total_amount": {"currency": "USD",

"value": "0.00"

},

"metadata": {"created_date": "2014-02-27 23:55:58 PST"

}

},

{"id": "INV2-5AYC-UE5K-XXEG-ABCD",

"number": "9879878979003790",

"status": "DRAFT",

"merchant_info": {"email": "merchant@example.com"

},

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

}

],

"shipping_info": {"first_name": "Sally",

"last_name": "Patient",

"business_name": "Not applicable"

},

"invoice_date": "2014-02-27 PST",

"note": "Medical Invoice 16 Jul, 2013 PST",

"total_amount": {"currency": "USD",

"value": "0.00"

},

"metadata": {"created_date": "2014-02-27 19:41:56 PST"

}

},

{"id": "INV2-C4QH-KEKM-C5QE-ABCD",

"number": "9879878979003789",

"status": "DRAFT",

"merchant_info": {"email": "merchant@example.com"

},

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

}

],

"shipping_info": {"first_name": "Sally",

"last_name": "Patient",

"business_name": "Not applicable"

},

"invoice_date": "2014-02-27 PST",

"note": "Medical Invoice 16 Jul, 2013 PST",

"total_amount": {"currency": "USD",

"value": "0.00"

},

"metadata": {"created_date": "2014-02-27 15:34:11 PST"

}

},

{"id": "INV2-YP6Y-9LJU-9NFS-ABCD",

"number": "9879878979003788",

"status": "DRAFT",

"merchant_info": {"email": "merchant@example.com"

},

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

}

],

"shipping_info": {"first_name": "Sally",

"last_name": "Patient",

"business_name": "Not applicable"

},

"invoice_date": "2014-02-27 PST",

"note": "Medical Invoice 16 Jul, 2013 PST",

"total_amount": {"currency": "USD",

"value": "12.00"

},

"metadata": {"created_date": "2014-02-27 15:34:01 PST"

}

}

],

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices?page=4&page_size=4&total_count_required=true",

"rel": "next",

"method": "GET"

},

{"href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices?page=2&page_size=4&total_count_required=true",

"rel": "previous",

"method": "GET"

}

]

operation/invoice.search Search for invoices

post/v1/invoicing/search

Try it

Searches for invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria.

SecurityOauth2

Request

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

The invoice status. To search by status, specify this value as an array. For example, "status": ["REFUNDED"]. The status indicates the phase of the invoice in its lifecycle:

Status	Occurs when
`CANCELLED`	A merchant or customer cancels a sent invoice.
`DRAFT`	A merchant creates a draft invoice. > Note: A customer cannot pay an invoice until a merchant sends it.
`MARKED_AS_PAID`	A merchant marks an invoice as paid after he or she receives a check or cash payment for the invoice.
`MARKED_AS_REFUNDED`	A merchant marks an invoice as refunded. > Note: A merchant can only mark a marked-as-paid invoice as refunded.
`PAID`	A customer fully pays an invoice. It is marked as paid through one or both of these methods: - A merchant marks an invoice as paid after he or she receives a check or cash payment from the customer for the invoice. - A customer makes an online payment for the invoice.
`PARTIALLY_PAID`	A merchant or customer fully pays an invoice through one or both of these methods: - A merchant marks an invoice as paid after he or she receives a check or cash payment from the customer for the invoice. - A customer makes an online payment for the invoice.
`PARTIALLY_REFUNDED`	A merchant partially refunds an invoice through one or both of these methods: - A merchant marks an invoice as refunded. To complete this action, the merchant must previously mark the invoice as paid. - A merchant makes an online refund for an online invoice payment.
`PAYMENT_PENDING`	A customer pays an invoice but the payment is pending for one of these reasons: - The payment is an uncleared eCheck. - The payment is in an accept or deny state upon which the merchant must act. - PayPal risk is reviewing the payment. > Note: Most payments never go into a payment-pending state.
`REFUNDED`	A merchant fully refunds an invoice through one or both of these methods: - A merchant marks an invoice as refunded. To complete this action, the merchant must previously mark the invoice as paid. - A merchant makes an online refund for an online invoice payment.
`SCHEDULED`	A merchant schedules an invoice to be emailed by PayPal on a specified date.
`SENT`	A merchant sends an invoice to the customer. After the merchant sends the invoice: - PayPal emails the invoice to the customer. - A Payment button appears on the invoice. The customer can now pay the invoice. - In a web app, the invoice appears as `Unpaid (sent)`.
`UNPAID`	A merchant sends an invoice and sets the `notify_merchant` and `notify_customer` query parameters to `false` to suppress the PayPal email notification. Then, the merchant manually sends the invoice link in his or her own email.

Enum:"DRAFT""SENT""SCHEDULED""PAID""MARKED_AS_PAID""CANCELLED""REFUNDED""PARTIALLY_REFUNDED""MARKED_AS_REFUNDED" | | lower_total_amount | string
The lower limit of the total amount. | | upper_total_amount | string
The upper limit of the total amount. | | start_invoice_date | string<date>
The start date for the invoice, in Internet date and time format. For example, yyyy- MM- dd z. | | end_invoice_date | string<date>
The end date for the invoice, in Internet date and time format. For example, yyyy- MM- dd z. | | start_due_date | string<date>
The start due date for the invoice, in Internet date and time format. For example, yyyy- MM- dd z. | | end_due_date | string<date>
The end due date for the invoice, in Internet date and time format. For example, yyyy- MM- dd z. | | start_payment_date | string<date>
The start payment date for the invoice, in Internet date and time format. For example, yyyy- MM- dd z. | | end_payment_date | string<date>
The end payment date for the invoice, in Internet date and time format. For example, yyyy- MM- dd z. | | start_creation_date | string<date>
The start creation date for the invoice, in Internet date and time format. For example, yyyy- MM- dd z. | | end_creation_date | string<date>
The end creation date for the invoice, in Internet date and time format. For example, yyyy- MM- dd z. | | page | number
The zero-relative start index of the entire list of merchant invoices to return in the response. So, a combination of page=0 and page_size=20 returns the first 20 invoices. A combination of page=20 and page_size=20 returns the next 20 invoices. | | page_size | number
The page size for the search results. | | total_count_required | boolean
Default:false
Indicates whether the response shows the total count. | | archived | boolean
Indicates whether to list merchant-archived invoices in the response. If true, response lists only merchant-archived invoices. If false, response lists only unarchived invoices. If null, response lists all invoices. |

Responses

200 A successful request returns the HTTP 200 OK status code and a JSON response body that lists the invoices that match the search criteria.

Request samples

Payload
cURL
Node.js
Java
Python

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

Sample 1 - 200 - Search for InvoicesSample 1 - 200 - Search for Invoices

Copy

`{"start_invoice_date": "2014-01-01 PST",

"end_invoice_date": "2014-03-26 PST",

"page": 0,

"page_size": 3,

"total_count_required": true

Response samples

application/json

Sample 1 - 200 - Search for InvoicesSample 1 - 200 - Search for Invoices

Copy

Expand allCollapse all

`{"invoices": [{"id": "INV2-KXVU-7Z64-DT6W-MG2X",

"number": "0001",

"status": "SENT",

"merchant_info": {"email": "dennis@example.com"

},

"billing_info": [{"email": "sally-patient@example.com"

}

],

"invoice_date": "2012-05-09 PST",

"payment_term": {"due_date": "2012-05-24 PST"

},

"total_amount": {"currency": "USD",

"value": "250"

},

"metadata": {"created_date": "2012-05-09 04:48:57 PST"

}

}

]

operation/invoice.send Send invoice

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

Try it

Sends an invoice, by ID, to a customer. To suppress the merchant's email notification, set the `notify_merchant` query parameter to `false`.

SecurityOauth2

Request

path Parameters


invoice_id required	string The ID of the invoice to send.

query Parameters


notify_merchant	boolean Default:true Indicates whether to send the invoice update notification to the merchant.

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

any

Responses

202 A successful request returns the HTTP 202 Accepted status code with no JSON response body.

Request samples

Payload
cURL
Node.js
Java
Python

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

Sample 1 - 202 - Send Invoice to PayerSample 1 - 202 - Send Invoice to Payer

Copy

{ }

Response samples

application/json

Sample 1 - 202 - Send Invoice to PayerSample 1 - 202 - Send Invoice to Payer

Copy

{ }

operation/invoice.schedule Schedule invoice

post/v1/invoicing/invoices/{invoice_id}/schedule

Try it

Schedules an invoice, by ID, to send on a future date. At 07:00 on that date in the preferred time zone of the merchant's PayPal account profile, PayPal emails an invoice notification to the merchant and the customer, adds an online payment button to the customer’s view of the invoice, and updates the invoice status to SENT.

SecurityOauth2

Request

path Parameters


invoice_id required	string The ID of the invoice to schedule.

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

any

Responses

202 A successful request returns the HTTP 202 Accepted status code and a JSON response body with a link to the invoice .

Request samples

Payload
cURL
Node.js
Java
Python

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

Sample 1 - 202 - Schedule InvoiceSample 1 - 202 - Schedule Invoice

Copy

{ }

Response samples

application/json

Sample 1 - 202 - Schedule InvoiceSample 1 - 202 - Schedule Invoice

Copy

Expand allCollapse all

`{"links": [{"href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7",

"rel": "self",

"method": "GET"

}

]

operation/invoice.remind Send invoice reminder

post/v1/invoicing/invoices/{invoice_id}/remind

Try it

Sends a reminder to the payer about an invoice, by ID. In the JSON request body, include a `notification` object that defines the subject of the reminder and other details.

SecurityOauth2

Request

path Parameters


invoice_id required	string The ID of the invoice for which to send a reminder.

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


subject	string The subject of the notification. Default is a generic subject.
note	string A note to the payer.
send_to_merchant	boolean Default:true Indicates whether to send a copy of the email to the merchant.
cc_emails	Array of strings<= 100 items An array of one or more CC: emails to which to send notification emails. If you omit this parameter, the API sends notification emails to all CC: email addresses that are part of the invoice. > Note: Valid values are email addresses in the `cc_info` array of the invoice.

Responses

202 A successful request returns the HTTP 202 Accepted status code with no JSON response body.

Request samples

Payload
cURL
Node.js
Java
Python

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

Sample 1 - 202 - Remind Payer to Pay InvoiceSample 1 - 202 - Remind Payer to Pay Invoice

Copy

Expand allCollapse all

`{"subject": "Past due",

"note": "Please pay soon",

"send_to_merchant": true,

"cc_emails": ["cc-email@example.com"

]

Response samples

application/json

Sample 1 - 202 - Remind Payer to Pay InvoiceSample 1 - 202 - Remind Payer to Pay Invoice

Copy

{ }

operation/invoice.cancel Cancel sent invoice

post/v1/invoicing/invoices/{invoice_id}/cancel

Try it

Cancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and CC: emails.

SecurityOauth2

Request

path Parameters


invoice_id required	string The ID of the invoice to cancel.

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


subject	string The subject of the notification. If left blank we include a generic subject.
note	string A note to the payer.
send_to_merchant	boolean Default:true Indicates whether to send the notification to the merchant.
send_to_payer	boolean Default:true Indicates whether to send the notification to the payer.
cc_emails	Array of strings<= 100 items An array of one or more CC: emails to which to send notification emails. If you omit this parameter, the API sends notification emails to all CC: email addresses that are part of the invoice. > Note: Additional email addresses are not supported.

Responses

204 A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples

Payload
cURL
Node.js
Java
Python

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

Sample 1 - 204 - Cancel InvoiceSample 1 - 204 - Cancel Invoice

Copy

Expand allCollapse all

`{"subject": "Invoice canceled",

"note": "Canceling this invoice per your request.",

"send_to_merchant": true,

"send_to_payer": true,

"cc_emails": ["cc-email@example.com"

]

Response samples

application/json

Sample 1 - 204 - Cancel InvoiceSample 1 - 204 - Cancel Invoice

Copy

{ }

operation/invoice.record-payment Mark invoice as paid

post/v1/invoicing/invoices/{invoice_id}/record-payment

Try it

Marks the status of an invoice, by ID, as paid.

SecurityOauth2

Request

path Parameters


invoice_id required	string The ID of the invoice to mark as paid.

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


date	string<date-time> The date when the invoice was paid, in Internet date and time format.
method required	string The payment mode or method. Enum:"BANK_TRANSFER""CASH""CHECK""CREDIT_CARD""DEBIT_CARD""PAYPAL""WIRE_TRANSFER""OTHER"
note	string A note associated with the payment.
amount	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Responses

200 A successful request returns the HTTP 200 OK status code with no JSON response body.

Request samples

Payload
cURL
Node.js
Java
Python

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

Sample 1 - 200 - Record Payment for InvoiceSample 1 - 200 - Record Payment for Invoice

Copy

Expand allCollapse all

`{"method": "CASH",

"date": "2013-11-06 03:30:00 PST",

"note": "I got the payment by cash!",

"amount": {"currency": "USD",

"value": "20.00"

}

Response samples

application/json

Sample 1 - 200 - Record Payment for InvoiceSample 1 - 200 - Record Payment for Invoice

Copy

{ }

operation/invoice.record-refund Mark invoice as refunded

post/v1/invoicing/invoices/{invoice_id}/record-refund

Try it

Marks the status of an invoice, by ID, as refunded.

SecurityOauth2

Request

path Parameters


invoice_id required	string The ID of the invoice to mark as refunded.

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


date	string<date-time> The date when the invoice was refunded, in Internet date and time format. For example, `2014-02-27 PST`.
note	string A note associated with the refund.
amount	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Responses

200 A successful request returns the HTTP 200 OK status code with no JSON response body.

Request samples

Payload
cURL
Node.js
Java
Python

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

Sample 1 - 200 - Record Refund for InvoiceSample 1 - 200 - Record Refund for Invoice

Copy

Expand allCollapse all

`{"date": "2013-11-10 14:00:00 PST",

"note": "Refunded by cash!",

"amount": {"currency": "USD",

"value": "20.00"

}

Response samples

application/json

Sample 1 - 200 - Record Refund for InvoiceSample 1 - 200 - Record Refund for Invoice

Copy

{ }

operation/invoice.get Show invoice details

get/v1/invoicing/invoices/{invoice_id}

Try it

Shows details for an invoice, by ID.

SecurityOauth2

Request

path Parameters


invoice_id required	string The ID of the invoice for which to show details.

Responses

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

Request samples

cURL
Node.js
Java
Python

Copy

curl -v -X GET https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7 \

Response samples

application/json

Sample 1 - 200 - Show Invoice DetailsSample 1 - 200 - Show Invoice Details

Copy

Expand allCollapse all

`{"id": "INV2-RF6D-L66T-D7H2-CRU7",

"number": "0002",

"status": "DRAFT",

"template_id": "TEMP-XYZ",

"merchant_info": {"email": "merchant@example.com",

"first_name": "Dennis",

"last_name": "Doctor",

"business_name": "Medical Professionals, LLC",

"phone": {"country_code": "1",

"national_number": "5032141716"

"address": {"line1": "1234 Main St.",

"city": "Portland",

"state": "OR",

"postal_code": "97217",

"country_code": "US"

}

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

}

],

"shipping_info": {"first_name": "Sally",

"last_name": "Patient",

"business_name": "Not applicable",

"address": {"line1": "1234 Broad St.",

"city": "Portland",

"state": "OR",

"postal_code": "97216",

"country_code": "US"

}

"items": [{"name": "Sutures",

"quantity": 100,

"unit_price": {"currency": "USD",

"value": "5.00"

}

}

],

"invoice_date": "2014-03-24 PDT",

"payment_term": {"term_type": "NET_45",

"due_date": "2014-05-08 PDT"

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"note": "Medical Invoice 16 Jul, 2013 PST",

"total_amount": {"currency": "USD",

"value": "500.00"

"metadata": {"created_date": "2014-03-24 12:11:52 PDT"

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7/send",

"rel": "send",

"method": "POST"

},

{"href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7",

"rel": "delete",

"method": "DELETE"

},

{"href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7",

"rel": "update",

"method": "PUT"

}

]

operation/invoice.update Update invoice

put/v1/invoicing/invoices/{invoice_id}

Try it

Fully updates an invoice, by ID. In the JSON request body, include a complete `invoice` object. This call does not support partial updates.

SecurityOauth2

Request

path Parameters


invoice_id required	string The ID of the invoice to update.

query Parameters


notify_merchant	boolean Default:true Indicates whether to send the invoice update notification to the merchant.

Request Body schema: application/json


number	string<= 25 characters The invoice number. If you omit this value, the default is the number that the API automatically increments from the last number.
billing_info	Array of objects (billing_info) = 1 items An array of billing information for the invoice recipient. > Note: This value is an array with only one element.
cc_info	Array of objects (Participant) An array of email addresses to which PayPal sends a copy of the invoice.
items	Array of objects (invoice_item) <= 100 items An array of invoice line item information.
invoice_date	string<date> The invoice date as specified by the sender, in Internet date and time format.
reference	string<= 60 characters The reference data, such as PO number.
allow_partial_payment	boolean Default:false Indicates whether the invoice allows a partial payment. If `false`, the invoice must be paid in full. If `true`, the invoice allows partial payments. > Note: This feature is not available for merchants in `India`, `Brazil`, or `Israel`.
tax_calculated_after_discount	boolean Default:false Indicates whether the tax is calculated before or after a discount. If `false`, the tax is calculated before a discount. If `true`, the tax is calculated after a discount.
tax_inclusive	boolean Default:false Indicates whether the unit price includes tax.
terms	string<= 4000 characters The general terms of the invoice.
note	string<= 4000 characters A note to the invoice recipient. The note also appears on the invoice notification email.
merchant_memo	string<= 500 characters A private bookkeeping memo for the merchant.
logo_url	string<uri><= 4000 characters The full URL to an external logo image. The logo must not be larger than 250 pixels wide by 90 pixels high. The logo must be stored on a secure server.
allow_tip	boolean Default:false 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. If `false`, the invoice does not show a tip amount field. > Note: This feature is not available for merchants in `Hong Kong`, `Taiwan`, `India`, or `Japan`.
template_id	string Default:"PayPal system template" This value is only used to determine the layout to display on the create or edit invoice experience, such as which fields to show and hide. It does not impact the view of the invoice that the customer receives. > Note: If you are just using the Invoicing APIs to create and send invoices, leave this field blank. The `template_id` is only needed if you use the Invoicing API to build a full invoicing solution that includes templates.
merchant_info required	object (merchant_info) The merchant business information that appears on the invoice.
shipping_info	object (shipping_info) The shipping information for the invoice recipient.
payment_term	object (payment_term) The payment term of the invoice. If you specify `term_type`, you cannot specify `due_date`, and vice versa.
discount	object (Discount) The discount as a percent or an amount value. For example, to specify 10%, enter `10`. Alternatively, to specify an amount of 5, enter `5`.
shipping_cost	object (shipping_cost) The shipping cost, as a percent or amount value.
custom	object (custom_amount) The custom amount to apply to an invoice. If you include a label, you must include a custom amount.
minimum_amount_due	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Responses

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

Request samples

Payload
cURL
Node.js
Java
Python

application/json

Sample 1 - 200 - Update InvoiceSample 1 - 200 - Update Invoice

Copy

Expand allCollapse all

`{"merchant_info": {"email": "merchant@example.com",

"first_name": "Dennis",

"last_name": "Doctor",

"business_name": "Medical Professionals, LLC",

"phone": {"country_code": "001",

"national_number": "5032141716"

"address": {"line1": "1234 Main St.",

"city": "Portland",

"state": "OR",

"postal_code": "97217",

"country_code": "US"

}

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

}

],

"items": [{"name": "Sutures",

"quantity": 100,

"unit_price": {"currency": "USD",

"value": "5"

}

}

],

"note": "Medical Invoice 16 Jul, 2013 PST",

"payment_term": {"term_type": "NET_45"

"shipping_info": {"first_name": "Sally",

"last_name": "Patient",

"business_name": "Not applicable",

"address": {"line1": "1234 Broad St.",

"city": "Portland",

"state": "OR",

"postal_code": "97216",

"country_code": "US"

}

Response samples

application/json

Sample 1 - 200 - Update InvoiceSample 1 - 200 - Update Invoice

Copy

Expand allCollapse all

`{"id": "INV2-8UZ6-Q3DK-VZXV-SXQB",

"number": "0014",

"status": "DRAFT",

"merchant_info": {"email": "merchant@example.com",

"first_name": "Dennis",

"last_name": "Doctor",

"business_name": "Medical Professionals, LLC",

"phone": {"country_code": "1",

"national_number": "5032141716"

"address": {"line1": "1234 Main St.",

"city": "Portland",

"state": "OR",

"postal_code": "97217",

"country_code": "US"

}

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

}

],

"shipping_info": {"first_name": "Sally",

"last_name": "Patient",

"business_name": "Not applicable",

"address": {"line1": "1234 Broad St.",

"city": "Portland",

"state": "OR",

"postal_code": "97216",

"country_code": "US"

}

"items": [{"name": "Sutures",

"quantity": 100,

"unit_price": {"currency": "USD",

"value": "5.00"

}

}

],

"invoice_date": "2014-03-24 PDT",

"payment_term": {"term_type": "NET_45",

"due_date": "2014-05-08 PDT"

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"note": "Medical Invoice 16 Jul, 2013 PST",

"total_amount": {"currency": "USD",

"value": "500.00"

}

operation/invoice.delete Delete draft invoice

delete/v1/invoicing/invoices/{invoice_id}

Try it

Deletes invoices in the DRAFT or SCHEDULED state, by ID. For invoices that have already been sent, you can cancel the invoice. After you delete a draft or scheduled invoice, you can no longer use it or show its details. However, you can reuse its invoice number.

SecurityOauth2

Request

path Parameters


invoice_id required	string The ID of the draft invoice to delete.

Responses

204 A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples

cURL
Node.js
Java
Python

Copy

curl -v -X DELETE https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-92MG-CNXV-ND7G-P3D2 \

Response samples

application/json

Sample 1 - 204 - Delete InvoiceSample 1 - 204 - Delete Invoice

Copy

{ }

operation/invoice.delete_external_payment Delete external payment

delete/v1/invoicing/invoices/{invoice_id}/payment-records/{transaction_id}

Try it

Deletes an external payment, by invoice ID and transaction ID.

SecurityOauth2

Request

path Parameters


invoice_id required	string The ID of the invoice from which to delete an external payment transaction.
transaction_id required	string The ID of the external payment transaction to delete.

Responses

204 A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples

cURL
Node.js
Java
Python

Copy

curl -v -X DELETE https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-TBRZ-SWBK-7FQ9-AC8F/payment-records/EXTR-86F38350LX4353815 \

Response samples

application/json

Sample 1 - 204 - Delete External TransactionSample 1 - 204 - Delete External Transaction

Copy

{ }

operation/invoice.delete_external_refund Delete external refund

delete/v1/invoicing/invoices/{invoice_id}/refund-records/{transaction_id}

Try it

Deletes an external refund, by invoice ID and transaction ID.

SecurityOauth2

Request

path Parameters


invoice_id required	string The ID of the invoice from which to delete the external refund transaction.
transaction_id required	string The ID of the external refund transaction to delete.

Responses

204 A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples

cURL
Node.js
Java
Python

Copy

curl -v -X DELETE https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-333R-YUQL-YNNN-D7WF/refund-records/EXTR-2LG703375E477444T \

Response samples

application/json

Sample 1 - 204 - Delete External Refund TransactionSample 1 - 204 - Delete External Refund Transaction

Copy

{ }

operation/invoice.qr_code Generate QR code

get/v1/invoicing/invoices/{invoice_id}/qr-code

Try it

Generates a QR code for an invoice, by ID. The QR code is a PNG image in Base64-encoded format that corresponds to the invoice ID. You can generate a QR code for an invoice and add it to a paper or PDF invoice. When customers use their mobile devices to scan the QR code, they are redirected to the PayPal mobile payment flow where they can view the invoice and pay online with PayPal or a credit card. Before you get a QR code, you must create an invoice and send an invoice to move the invoice from a draft to payable state. Do not include an email address if you do not want the invoice emailed.

SecurityOauth2

Request

path Parameters


invoice_id required	string The ID of the invoice for which to generate a QR code.

query Parameters


width	integer Default:500 The width, in pixels, of the QR code image. Value is from `150` to `500`.
height	integer Default:500 The height, in pixels, of the QR code image. Value is from `150` to `500`.

Responses

200 A successful request returns the HTTP 200 OK status code and a JSON response body that shows the QR code as a PNG image.

Request samples

cURL
Node.js
Java
Python

Copy

curl -v -X GET https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-S6FG-ZZCK-VXMM-8KKP/qr-code \

Response samples

application/json

Sample 1 - 200 - Generate QR Code for InvoiceSample 1 - 200 - Generate QR Code for Invoice

Copy

`{"image": "iVBORw0KGgoAA......XUDM"

operation/invoice.next_invoice_number Generate invoice number

post/v1/invoicing/invoices/next-invoice-number

Try it

Generates the next invoice number that is available to the merchant. The next invoice number uses the prefix and suffix from the last invoice number and increments the number by one. For example, the next invoice number after `INVOICE-1234` is `INVOICE-1235`.

SecurityOauth2

Request

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

any

Responses

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

Request samples

Payload
cURL
Node.js
Java
Python

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

Sample 1 - 200 - Generate Next Invoice NumberSample 1 - 200 - Generate Next Invoice Number

Copy

{ }

Response samples

application/json

Sample 1 - 200 - Generate Next Invoice NumberSample 1 - 200 - Generate Next Invoice Number

Copy

`{"number": "ee0044"

operation/template.create Create template

post/v1/invoicing/templates

Try it

Creates an invoice template. You can use details from this template to create an invoice. You can create up to 50 templates.

SecurityOauth2

Request

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


name	string The template name. > Note: The template name must be unique.
default	boolean Indicates whether this template is the default merchant template. A merchant can have one default template.
settings	Array of objects (template_settings) An array of template settings that describe which fields to show or hide when creating an invoice.
unit_of_measure	string The unit of measure for the template. Enum:"HOURS""QUANTITY""AMOUNT"
template_data	object (template_data) The template data.

Responses

201 Created

Request samples

Payload
cURL
Node.js
Java
Python

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

Sample 1 - 201 - Create TemplateSample 1 - 201 - Create Template

Copy

Expand allCollapse all

`{"name": "Hours Template",

"default": true,

"unit_of_measure": "HOURS",

"template_data": {"merchant_info": {"email": "doctor@example.com",

"first_name": "Dennis",

"last_name": "Doctor",

"business_name": "Medical Professionals, LLC",

"phone": {"country_code": "001",

"national_number": "5032141716"

"address": {"line1": "1234 Main St.",

"city": "Portland",

"state": "OR",

"postal_code": "97217",

"country_code": "US"

}

"items": [{"name": "Nutri Bullet",

"quantity": 1,

"unit_price": {"currency": "USD",

"value": "50.00"

}

}

],

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"note": "Thank you for your business.",

"logo_url": "https://example.com/v1/images/redDot.jpeg"

"settings": [{"field_name": "items.date",

"display_preference": {"hidden": true

}

},

{"field_name": "custom",

"display_preference": {"hidden": true

}

}

]

Response samples

application/json

Sample 1 - 201 - Create TemplateSample 1 - 201 - Create Template

Copy

Expand allCollapse all

`{"template_id": "TEMP-XYZ",

"name": "Hours Template",

"default": true,

"unit_of_measure": "HOURS",

"template_data": {"merchant_info": {"email": "doctor@example.com",

"first_name": "Dennis",

"last_name": "Doctor",

"business_name": "Medical Professionals, LLC",

"phone": {"country_code": "001",

"national_number": "5032141716"

"address": {"line1": "1234 Main St.",

"city": "Portland",

"state": "OR",

"postal_code": "97217",

"country_code": "US"

}

"items": [{"name": "Nutri Bullet",

"quantity": 1,

"unit_price": {"currency": "USD",

"value": "50.00"

}

}

],

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"note": "Thank you for your business.",

"logo_url": "https://example.com/v1/images/redDot.jpeg"

"settings": [{"field_name": "items.date",

"display_preference": {"hidden": true

}

},

{"field_name": "custom",

"display_preference": {"hidden": true

}

}

],

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",

"rel": "self",

"method": "GET"

},

{"href": "https://api-m.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",

"rel": "replace",

"method": "PUT"

},

{"href": "https://api-m.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",

"rel": "delete",

"method": "DELETE"

}

]

operation/template.get_templates List templates

get/v1/invoicing/templates

Try it

Lists merchant-created templates with associated details. The associated details include the email addresses, postal addresses, and phone numbers from the user's PayPal profile.

The user can select which values to show in the business information section of their template.

SecurityOauth2

Request

query Parameters


fields	string Default:"all" The fields to return in the response. Value is `all` or `none`. To return only the template name, ID, and default attributes, specify `none`.

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

any

Responses

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

Request samples

Payload
cURL
Node.js
Java
Python

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

Copy

{ }

Response samples

application/json

Sample 1 - 200 - List TemplatesSample 1 - 200 - List Templates

Copy

Expand allCollapse all

`{"addresses": [{"line1": "2211 N 1st Street",

"city": "San Jose",

"postal_code": "95131",

"state": "CA",

"country_code": "US"

}

],

"emails": ["invoicing-merchant@example.com",

"invoicing-merch-store2@example.com"

],

"phones": [{"country_code": "1",

"national_number": "4085057783"

},

{"country_code": "1",

"national_number": "4088064703"

}

],

"templates": [{"template_id": "TEMP-XYZ",

"name": "Hours Template",

"default": true,

"unit_of_measure": "HOURS",

"template_data": {"merchant_info": {"email": "doctor@example.com",

"first_name": "Dennis",

"last_name": "Doctor",

"business_name": "Medical Professionals, LLC",

"phone": {"country_code": "001",

"national_number": "5032141716"

},

"address": {"line1": "1234 Main St.",

"city": "Portland",

"state": "OR",

"postal_code": "97217",

"country_code": "US"

}

},

"items": [{"name": "Nutri Bullet",

"quantity": 1,

"unit_price": {"currency": "USD",

"value": "50.00"

}

}

],

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"note": "Thank you for your business.",

"logo_url": "https://example.com/v1/images/redDot.jpeg"

},

"settings": [{"field_name": "items.date",

"display_preference": {"hidden": true

}

},

{"field_name": "custom",

"display_preference": {"hidden": true

}

}

],

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",

"rel": "self",

"method": "GET"

},

{"href": "https://api-m.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",

"rel": "replace",

"method": "PUT"

},

{"href": "https://api-m.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",

"rel": "delete",

"method": "DELETE"

}

]

}

],

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/invoicing/templates",

"rel": "collection",

"method": "GET"

}

]

operation/template.get Show template details

get/v1/invoicing/templates/{template_id}

Try it

Shows details for a template, by ID.

SecurityOauth2

Request

path Parameters


template_id required	string The ID of the template for which to show details.

Responses

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

Request samples

cURL
Node.js
Java
Python

Copy

curl -v -X GET https://api-m.sandbox.paypal.com/v1/invoicing/templates/TEMP-0JV3858360943364J \

Response samples

application/json

Sample 1 - 200 - Show Template DetailsSample 1 - 200 - Show Template Details

Copy

Expand allCollapse all

`{"template_id": "TEMP-XYZ",

"name": "Hours Template",

"default": true,

"unit_of_measure": "HOURS",

"template_data": {"merchant_info": {"email": "doctor@example.com",

"first_name": "Dennis",

"last_name": "Doctor",

"business_name": "Medical Professionals, LLC",

"phone": {"country_code": "001",

"national_number": "5032141716"

"address": {"line1": "1234 Main St.",

"city": "Portland",

"state": "OR",

"postal_code": "97217",

"country_code": "US"

}

"items": [{"name": "Nutri Bullet",

"quantity": 1,

"unit_price": {"currency": "USD",

"value": "50.00"

}

}

],

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"note": "Thank you for your business.",

"logo_url": "https://example.com/v1/images/redDot.jpeg"

"settings": [{"field_name": "items.date",

"display_preference": {"hidden": true

}

},

{"field_name": "custom",

"display_preference": {"hidden": true

}

}

],

operation/template.delete Delete template

delete/v1/invoicing/templates/{template_id}

Try it

Deletes a template, by ID.

SecurityOauth2

Request

path Parameters


template_id required	string The ID of the template to delete.

Responses

204 A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples

cURL
Node.js
Java
Python

Copy

curl -v -X DELETE https://api-m.sandbox.paypal.com/v1/invoicing/templates/TEMP-0JV3858360943364J \

Response samples

application/json

Sample 1 - 204 - Delete TemplateSample 1 - 204 - Delete Template

Copy

{ }

operation/template.update Update template

put/v1/invoicing/templates/{template_id}

Try it

Updates a template, by ID. In the JSON request body, specify a complete `template` object. The update method does not support partial updates.

SecurityOauth2

Request

path Parameters


template_id required	string The ID of the template to update.

Request Body schema: application/json


name	string The template name. > Note: The template name must be unique.
default	boolean Indicates whether this template is the default merchant template. A merchant can have one default template.
settings	Array of objects (template_settings) An array of template settings that describe which fields to show or hide when creating an invoice.
unit_of_measure	string The unit of measure for the template. Enum:"HOURS""QUANTITY""AMOUNT"
template_data	object (template_data) The template data.

Responses

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

Request samples

Payload
cURL
Node.js
Java
Python

application/json

Sample 1 - 200 - Update TemplateSample 1 - 200 - Update Template

Copy

Expand allCollapse all

`{"template_id": "TEMP-XYZ",

"name": "Hours Template",

"default": true,

"unit_of_measure": "HOURS",

"template_data": {"merchant_info": {"email": "doctor@example.com",

"first_name": "Dennis",

"last_name": "Doctor",

"business_name": "Medical Professionals, LLC",

"phone": {"country_code": "001",

"national_number": "5032141716"

"address": {"line1": "1234 Main St.",

"city": "Portland",

"state": "OR",

"postal_code": "97217",

"country_code": "US"

}

"items": [{"name": "Nutri Bullet",

"quantity": 1,

"unit_price": {"currency": "USD",

"value": "50.00"

}

}

],

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"note": "Thank you for your business.",

"logo_url": "https://example.com/v1/images/redDot.jpeg"

"settings": [{"field_name": "items.date",

"display_preference": {"hidden": true

}

},

{"field_name": "custom",

"display_preference": {"hidden": true

}

}

]

Response samples

application/json

Sample 1 - 200 - Update TemplateSample 1 - 200 - Update Template

Copy

Expand allCollapse all

`{"template_id": "TEMP-XYZ",

"name": "Hours Template",

"default": true,

"unit_of_measure": "HOURS",

"template_data": {"merchant_info": {"email": "doctor@example.com",

"first_name": "Dennis",

"last_name": "Doctor",

"business_name": "Medical Professionals, LLC",

"phone": {"country_code": "001",

"national_number": "5032141716"

"address": {"line1": "1234 Main St.",

"city": "Portland",

"state": "OR",

"postal_code": "97217",

"country_code": "US"

}

"items": [{"name": "Nutri Bullet",

"quantity": 1,

"unit_price": {"currency": "USD",

"value": "50.00"

}

}

],

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"note": "Thank you for your business.",

"logo_url": "https://example.com/v1/images/redDot.jpeg"

"settings": [{"field_name": "items.date",

"display_preference": {"hidden": true

}

},

{"field_name": "custom",

"display_preference": {"hidden": true

}

}

],

tag/Errors Errors

section/AUTHORIZATION_ERROR AUTHORIZATION_ERROR

Message:

Authorization error occurred.

Description: Check your credentials.

section/BUSINESS_ERROR BUSINESS_ERROR

Message:

Invoicing business error.

Description: See the message for a brief description of the error.

section/INTERNAL_SERVICE_ERROR INTERNAL_SERVICE_ERROR

Message:

An internal service error has occurred.

Description: Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.

section/MALFORMED_REQUEST_ERROR MALFORMED_REQUEST_ERROR

Message:

JSON request malformed.

Description: Correct the JSON request body and resend the request.

section/RESOURCE_NOT_FOUND_ERROR RESOURCE_NOT_FOUND_ERROR

Message:

Resource not found.

Description: The resource was not found.

section/UNKNOWN_ERROR UNKNOWN_ERROR

Message:

Unknown exception occurred.

Description: If this error continues, contact PayPal Merchant Technical Support.

section/USER_BUSINESS_ERROR USER_BUSINESS_ERROR

Message:

User business error.

Description: See the message for a brief description of the error.

section/VALIDATION_ERROR VALIDATION_ERROR

Message:

Invalid request - see details.

Description: One or more validation errors have occurred. Review the details for specific validation errors.

tag/Definitions Definitions

schema/common_components-v1-schema-json-openapi-2.0-address.json Address

The address, which is either a billing address or shipping address in a payment.


line1 required	string The first line of the address. For example, number or street.
line2	string The second line of the address. For example, suite or apartment number.
city required	string The city name.
country_code required	string The two-character ISO 3166-1 code that identifies the country or region. > Note: The country code for Great Britain is `GB` and not `UK` as is used in that country's top-level domain names. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
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.
state	string The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, China, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.
phone	string<phone> The phone number, in its canonical international E.164 numbering plan format.

Copy

`{"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

schema/amount-summary.json amount_summary

The summary of the invoice total and paid and refunded amounts, grouped by currency code.


total_amount	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.
paid_amount	object (payment_summary) The payment and refund summary.
refunded_amount	object (payment_summary) The payment and refund summary.

Copy

Expand allCollapse all

`{"total_amount": {"currency": "string",

"value": "string"

"paid_amount": {"paypal": {"currency": "string",

"value": "string"

"other": {"currency": "string",

"value": "string"

}

"refunded_amount": {"paypal": {"currency": "string",

"value": "string"

"other": {"currency": "string",

"value": "string"

}

schema/billing-info.json billing_info

The billing information for the invoice recipient.


email	string<email><= 260 characters The invoice recipient email address. If you omit this value, the invoice is payable and a notification email is not sent.
first_name	string<= 30 characters The invoice recipient's first name.
last_name	string<= 30 characters The invoice recipient's last name.
business_name	string<= 100 characters The invoice recipient's business name.
language	string The language in which the invoice recipient's email appears. 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 is sent in the language of the merchant's PayPal account. Enum:"da_DK""de_DE""en_AU""en_GB""en_US""es_ES""es_XC""fr_CA""fr_FR""fr_XC""he_IL""id_ID""it_IT""ja_JP""nl_NL""no_NO""pl_PL""pt_BR""pt_PT""ru_RU""sv_SE""th_TH""tr_TR""zh_CN""zh_HK""zh_TW""zh_XC"
additional_info	string<= 40 characters Any additional information about the recipient.
phone	object (Phone) The phone number.
address	object (Address) The address, which is either a billing address or shipping address in a payment.

Copy

Expand allCollapse all

`{"email": "user@example.com",

"first_name": "string",

"last_name": "string",

"business_name": "string",

"language": "da_DK",

"additional_info": "string",

"phone": {"country_code": "str",

"national_number": "string"

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

}

schema/cancel-notification.json cancel_notification

Cancels an email or SMS notification.


subject	string The subject of the notification. If left blank we include a generic subject.
note	string A note to the payer.
send_to_merchant	boolean Default:true Indicates whether to send the notification to the merchant.
send_to_payer	boolean Default:true Indicates whether to send the notification to the payer.
cc_emails	Array of strings<= 100 items An array of one or more CC: emails to which to send notification emails. If you omit this parameter, the API sends notification emails to all CC: email addresses that are part of the invoice. > Note: Additional email addresses are not supported.

Copy

Expand allCollapse all

`{"subject": "string",

"note": "string",

"send_to_merchant": true,

"send_to_payer": true,

"cc_emails": ["string"

]

schema/common_components-v1-schema-json-openapi-2.0-currency.json Currency

The currency and amount for a financial transaction, such as a balance or payment due.


currency required	string The three-character ISO-4217 currency code.
value required	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. For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

Copy

`{"currency": "string",

"value": "string"

schema/custom-amount.json custom_amount

The custom amount to apply to an invoice. If you include a label, you must include a custom amount.


label	string<= 50 characters The custom amount label.
amount	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Copy

Expand allCollapse all

`{"label": "string",

"amount": {"currency": "string",

"value": "string"

}

schema/discount.json Discount

The discount as a percent or an amount value. For example, to specify 10%, enter 10. Alternatively, to specify an amount of 5, enter 5.


percent	number The discount as a percentage value. Value is from `0` to `100`. Supports up to five decimal places.
amount	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Copy

Expand allCollapse all

`{"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

schema/email.json Email

The participant's email address.

string<email> (Email)

The participant's email address.

Copy

"user@example.com"

schema/common_components-v1-schema-json-openapi-2.0-error.json Error

The error information.


name required	string The human-readable, unique name of the error.
debug_id	string The PayPal internal ID. Used for correlation purposes.
message required	string The message that describes the error.
information_link required	string The URI to detailed information related to this error for the developer.
details	Array of objects (Error Details) An array of additional details for the error.

Copy

Expand allCollapse all

`{"name": "string",

"debug_id": "string",

"message": "string",

"information_link": "string",

"details": [{"field": "string",

"issue": "string"

}

]

schema/common_components-v1-schema-json-openapi-2.0-error_details.json Error Details

The error details. Required for client-side 4XX errors.


field required	string The name of the field that caused the error.
issue required	string The reason for the error.

Copy

`{"field": "string",

"issue": "string"

schema/file-attachment.json file_attachment

The file that is attached to an invoice or template.


name	string The name of the attached file.
url	string<uri> The URL of the attached file. Use this URL to download the file.

Copy

`{"name": "string",

"url": "http://example.com"

schema/invoice.json Invoice

The invoice details.

The invoice status. When you search for invoices, you must specify this value as an array. For example, "status": ["REFUNDED"]. The status indicates the phase of an invoice in its lifecycle. The status also indicates whether the invoice is unpaid, partially paid, fully paid, partially refunded, or fully refunded. An invoice payment can be either:

Connected to an invoice. The customer clicks Pay on the invoice to make a payment. The payment is automatically recorded.
Disconnected from an invoice. The customer pays by check, wire transfer, or another method. The merchant manually records the payment.

Similarly, an invoice refund can be disconnected from an invoice. The merchant refunds a payment by check, wire transfer, or another method and manually records the refund. This table lists the typical order through which an invoice moves through status values:

Status	Occurs when
`DRAFT`	A merchant creates a draft invoice. > Note: A customer cannot pay an invoice with this status. A customer cannot pay an invoice until it has a status of `SENT` or `UNPAID`.
`UNPAID`	A merchant chooses to suppress the PayPal email notification when he or she sends the invoice through the API or the Create Invoice page, and then manually sends the invoice link in his or her own email. To send an invoice without email notification, the merchant either: - Sets the `notify_merchant` and `notify_customer` query parameters to `false` when he or she sends the invoice. - Selects Share link myself from the Send menu when he or she sends the invoice through the web UI Create Invoice page.
`SENT`	A merchant accepts the default PayPal email notification when he or she sends the invoice through the API or the Create Invoice page. PayPal automatically emails the invoice to the customer and a Pay button appears on the invoice, which enables the customer to pay the invoice. In a web app, the invoice appears as `Unpaid (sent)`.
`SCHEDULED`	A merchant schedules an invoice to send on a future date. At 07:00 on that date in the preferred time zone of the merchant's PayPal account profile, PayPal emails an invoice notification to the merchant and the customer, adds an online payment button to the customer’s view of the invoice, and updates the invoice status to `SENT`.
`PARTIALLY_PAID`	A customer makes a partial payment for the invoice through one of these methods: - A customer makes a disconnected partial payment for the invoice and the merchant manually marks the invoice as paid. - A customer makes a connected partial payment for the invoice.
`PAYMENT_PENDING`	A customer pays an invoice but the payment is pending for one of these reasons: - The payment is an uncleared eCheck. - The merchant must either accept the payment before it clears or deny the payment. - PayPal risk is reviewing the payment. > Note: Most payments never go into a payment-pending state.
`PAID`	A customer fully pays the invoice through one of these methods: - A customer makes a connected full payment for the invoice. - A customer makes a connected partial payment for the invoice. Then, the customer makes a disconnected payment, such as a check payment, to pay the balance of the invoice and the merchant manually marks the invoice as fully paid.
`MARKED_AS_PAID`	A customer makes a disconnected payment for the balance of the invoice. The merchant manually marks the invoice as paid.
`CANCELLED`	A merchant or customer cancels a sent invoice. You can cancel an invoice in `SENT` or `UNPAID` status.
`REFUNDED`	A merchant fully refunds an invoice through one these methods: - A merchant makes a connected full refund for the invoice. - A merchant makes a connected partial refund for the invoice. Then, the merchant makes a disconnected refund, such as a check payment, for the invoice balance and manually marks the invoice as fully refunded.
`PARTIALLY_REFUNDED`	A merchant partially refunds an invoice through one or both of these methods: - A merchant makes a disconnected partial refund, such as a check payment, for the invoice and marks the invoice as partially refunded. To complete this action, the merchant must previously mark the invoice as paid. - A merchant makes a connected partial refund for a connected partial payment.
`MARKED_AS_REFUNDED`	A merchant makes a disconnected refund, such as a check payment, for the invoice balance and manually marks the invoice as fully refunded. > Note: A merchant can only mark a marked-as-paid invoice as refunded.

Enum:"DRAFT""UNPAID""SENT""SCHEDULED""PARTIALLY_PAID""PAYMENT_PENDING""PAID""MARKED_AS_PAID""CANCELLED""REFUNDED""PARTIALLY_REFUNDED""MARKED_AS_REFUNDED" | | billing_info | Array of objects (billing_info) = 1 items
An array of billing information for the invoice recipient.
> Note: This value is an array with only one element. | | cc_info | Array of objects (Participant)
An array of email addresses to which PayPal sends a copy of the invoice. | | items | Array of objects (invoice_item) <= 100 items
An array of invoice line item information. | | invoice_date | string<date>
The invoice date as specified by the sender, in Internet date and time format. | | reference | string<= 60 characters
The reference data, such as PO number. | | allow_partial_payment | boolean
Default:false
Indicates whether the invoice allows a partial payment. If false, the invoice must be paid in full. If true, the invoice allows partial payments.
> Note: This feature is not available for merchants in India, Brazil, or Israel. | | tax_calculated_after_discount | boolean
Default:false
Indicates whether the tax is calculated before or after a discount. If false, the tax is calculated before a discount. If true, the tax is calculated after a discount. | | tax_inclusive | boolean
Default:false
Indicates whether the unit price includes tax. | | terms | string<= 4000 characters
The general terms of the invoice. | | note | string<= 4000 characters
A note to the invoice recipient. The note also appears on the invoice notification email. | | merchant_memo | string<= 500 characters
A private bookkeeping memo for the merchant. | | logo_url | string<uri><= 4000 characters
The full URL to an external logo image. The logo must not be larger than 250 pixels wide by 90 pixels high. The logo must be stored on a secure server. | | payments | Array of objects (payment_detail) <= 1 items
An array of payment details for the invoice. | | refunds | Array of objects (refund_detail) <= 1 items
An array of refund details for the invoice. | | attachments | Array of objects (file_attachment)
An array of PayPal file IDs for the files that are attached to an invoice. You can attach up to five files. | | allow_tip | boolean
Default:false
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. If false, the invoice does not show a tip amount field.
> Note: This feature is not available for merchants in Hong Kong, Taiwan, India, or Japan. | | template_id | string
Default:"PayPal system template"
This value is only used to determine the layout to display on the create or edit invoice experience, such as which fields to show and hide. It does not impact the view of the invoice that the customer receives.
> Note: If you are just using the Invoicing APIs to create and send invoices, leave this field blank. The template_id is only needed if you use the Invoicing API to build a full invoicing solution that includes templates. | | links | Array of objects (Link Description)
An array of request-related HATEOAS links. | | merchant_info
required | object (merchant_info)
The merchant business information that appears on the invoice. | | shipping_info | object (shipping_info)
The shipping information for the invoice recipient. | | payment_term | object (payment_term)
The payment term of the invoice. If you specify term_type, you cannot specify due_date, and vice versa. | | discount | object (Discount)
The discount as a percent or an amount value. For example, to specify 10%, enter 10. Alternatively, to specify an amount of 5, enter 5. | | shipping_cost | object (shipping_cost)
The shipping cost, as a percent or amount value. | | custom | object (custom_amount)
The custom amount to apply to an invoice. If you include a label, you must include a custom amount. | | minimum_amount_due | object (Currency)
The currency and amount for a financial transaction, such as a balance or payment due. | | total_amount | object (Currency)
The currency and amount for a financial transaction, such as a balance or payment due. | | metadata | object (Metadata)
The audit metadata. | | paid_amount | object (payment_summary)
The payment and refund summary. | | refunded_amount | object (payment_summary)
The payment and refund summary. |

Copy

Expand allCollapse all

`{"id": "string",

"number": "string",

"status": "DRAFT",

"billing_info": [{"email": "user@example.com",

"first_name": "string",

"last_name": "string",

"business_name": "string",

"language": "da_DK",

"additional_info": "string",

"phone": {"country_code": "str",

"national_number": "string"

},

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

}

}

],

"cc_info": [{"email": "user@example.com"

}

],

"items": [{"name": "string",

"description": "string",

"quantity": 0,

"date": "2019-08-24",

"unit_of_measure": "QUANTITY",

"unit_price": {"currency": "string",

"value": "string"

},

"tax": {"name": "string",

"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

},

"discount": {"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

}

}

],

"invoice_date": "2019-08-24",

"reference": "string",

"allow_partial_payment": false,

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"terms": "string",

"note": "string",

"merchant_memo": "string",

"logo_url": "http://example.com",

"payments": [{"type": "PAYPAL",

"transaction_id": "string",

"transaction_type": "SALE",

"date": "2019-08-24T14:15:22Z",

"method": "BANK_TRANSFER",

"note": "string",

"amount": {"currency": "string",

"value": "string"

}

}

],

"refunds": [{"type": "PAYPAL",

"transaction_id": "string",

"date": "2019-08-24T14:15:22Z",

"note": "string",

"amount": {"currency": "string",

"value": "string"

}

}

],

"attachments": [{"name": "string",

"url": "http://example.com"

}

],

"allow_tip": false,

"template_id": "PayPal system template",

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"merchant_info": {"email": "user@example.com",

"business_name": "string",

"first_name": "string",

"last_name": "string",

"website": "http://example.com",

"tax_id": "string",

"additional_info": "string",

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

"phone": {"country_code": "str",

"national_number": "string"

"fax": {"country_code": "str",

"national_number": "string"

}

"shipping_info": {"first_name": "string",

"last_name": "string",

"business_name": "string",

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

}

"payment_term": {"term_type": "DUE_ON_RECEIPT",

"due_date": "2019-08-24"

"discount": {"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

"shipping_cost": {"amount": {"currency": "string",

"value": "string"

"tax": {"name": "string",

"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

"custom": {"label": "string",

"amount": {"currency": "string",

"value": "string"

}

"minimum_amount_due": {"currency": "string",

"value": "string"

"total_amount": {"currency": "string",

"value": "string"

"metadata": {"created_date": "2019-08-24T14:15:22Z",

"created_by": "string",

"cancelled_date": "2019-08-24T14:15:22Z",

"cancelled_by": "string",

"last_updated_date": "2019-08-24T14:15:22Z",

"last_updated_by": "string",

"first_sent_date": "2019-08-24T14:15:22Z",

"last_sent_date": "2019-08-24T14:15:22Z",

"last_sent_by": "string",

"payer_view_url": "http://example.com"

"paid_amount": {"paypal": {"currency": "string",

"value": "string"

"other": {"currency": "string",

"value": "string"

}

"refunded_amount": {"paypal": {"currency": "string",

"value": "string"

"other": {"currency": "string",

"value": "string"

}

schema/invoice_number.json Invoice Number

The invoice number.


number	string The invoice number. If you omit this value from the request, the default is the number that the API automatically increments from the last number.

Copy

`{"number": "string"

schema/invoice-item.json invoice_item

The invoice line item information.


name required	string<= 200 characters The item name.
description	string<= 1000 characters The item description.
quantity required	number The item quantity. Value is from `-10000` to `10000`. Supports up to five decimal places.
date	string<date> The date when the item or service was provided, in Internet date and time format. For example, yyyy- MM- dd z.
unit_of_measure	string The unit of measure for the invoiced item. For `AMOUNT` the `unit_price` and `quantity` 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. Enum:"QUANTITY""HOURS""AMOUNT"
unit_price required	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.
tax	object (Tax) The tax information.
discount	object (Discount) The discount as a percent or an amount value. For example, to specify 10%, enter `10`. Alternatively, to specify an amount of 5, enter `5`.

Copy

Expand allCollapse all

`{"name": "string",

"description": "string",

"quantity": 0,

"date": "2019-08-24",

"unit_of_measure": "QUANTITY",

"unit_price": {"currency": "string",

"value": "string"

"tax": {"name": "string",

"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

"discount": {"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

schema/invoices.json Invoices

A list of merchant invoices. Can include the total invoices count and HATEOAS links for navigation.


total_count	integer The total number of invoices that match the search criteria.
invoices	Array of objects (Invoice) An array of invoice-level details. > Note: This array does not return item details for the invoice.
links	Array of objects (Link Description) An array of request-related HATEOAS links.

Copy

Expand allCollapse all

`{"total_count": 0,

"invoices": [{"id": "string",

"number": "string",

"status": "DRAFT",

"billing_info": [{"email": "user@example.com",

"first_name": "string",

"last_name": "string",

"business_name": "string",

"language": "da_DK",

"additional_info": "string",

"phone": {"country_code": "str",

"national_number": "string"

},

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

}

}

],

"cc_info": [{"email": "user@example.com"

}

],

"items": [{"name": "string",

"description": "string",

"quantity": 0,

"date": "2019-08-24",

"unit_of_measure": "QUANTITY",

"unit_price": {"currency": "string",

"value": "string"

},

"tax": {"name": "string",

"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

},

"discount": {"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

}

}

],

"invoice_date": "2019-08-24",

"reference": "string",

"allow_partial_payment": false,

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"terms": "string",

"note": "string",

"merchant_memo": "string",

"logo_url": "http://example.com",

"payments": [{"type": "PAYPAL",

"transaction_id": "string",

"transaction_type": "SALE",

"date": "2019-08-24T14:15:22Z",

"method": "BANK_TRANSFER",

"note": "string",

"amount": {"currency": "string",

"value": "string"

}

}

],

"refunds": [{"type": "PAYPAL",

"transaction_id": "string",

"date": "2019-08-24T14:15:22Z",

"note": "string",

"amount": {"currency": "string",

"value": "string"

}

}

],

"attachments": [{"name": "string",

"url": "http://example.com"

}

],

"allow_tip": false,

"template_id": "PayPal system template",

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"merchant_info": {"email": "user@example.com",

"business_name": "string",

"first_name": "string",

"last_name": "string",

"website": "http://example.com",

"tax_id": "string",

"additional_info": "string",

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

},

"phone": {"country_code": "str",

"national_number": "string"

},

"fax": {"country_code": "str",

"national_number": "string"

}

},

"shipping_info": {"first_name": "string",

"last_name": "string",

"business_name": "string",

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

}

},

"payment_term": {"term_type": "DUE_ON_RECEIPT",

"due_date": "2019-08-24"

},

"discount": {"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

},

"shipping_cost": {"amount": {"currency": "string",

"value": "string"

},

"tax": {"name": "string",

"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

}

},

"custom": {"label": "string",

"amount": {"currency": "string",

"value": "string"

}

},

"minimum_amount_due": {"currency": "string",

"value": "string"

},

"total_amount": {"currency": "string",

"value": "string"

},

"metadata": {"created_date": "2019-08-24T14:15:22Z",

"created_by": "string",

"cancelled_date": "2019-08-24T14:15:22Z",

"cancelled_by": "string",

"last_updated_date": "2019-08-24T14:15:22Z",

"last_updated_by": "string",

"first_sent_date": "2019-08-24T14:15:22Z",

"last_sent_date": "2019-08-24T14:15:22Z",

"last_sent_by": "string",

"payer_view_url": "http://example.com"

},

"paid_amount": {"paypal": {"currency": "string",

"value": "string"

},

"other": {"currency": "string",

"value": "string"

}

},

"refunded_amount": {"paypal": {"currency": "string",

"value": "string"

},

"other": {"currency": "string",

"value": "string"

}

}

}

],

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

]

schema/common_components-v3-schema-json-openapi-2.0-link_description.json Link Description

The request-related HATEOAS link information.


href required	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. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
rel required	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	string The HTTP method required to make the related call. Enum:"GET""POST""PUT""DELETE""HEAD""CONNECT""OPTIONS""PATCH"

Copy

`{"href": "string",

"rel": "string",

"method": "GET"

schema/merchant-info.json merchant_info

The merchant business information that appears on the invoice.


email	string<email><= 260 characters The merchant email address. This email must be listed in the merchant'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.
business_name	string<= 100 characters The merchant's business name.
first_name	string<= 256 characters The merchant's first name.
last_name	string<= 256 characters The merchant's last name.
website	string<uri><= 2048 characters The merchant's website.
tax_id	string<= 100 characters The merchant's tax ID.
additional_info	string<= 40 characters Any additional information, such as business hours.
address	object (Address) The address, which is either a billing address or shipping address in a payment.
phone	object (Phone) The phone number.
fax	object (Phone) The phone number.

Copy

Expand allCollapse all

`{"email": "user@example.com",

"business_name": "string",

"first_name": "string",

"last_name": "string",

"website": "http://example.com",

"tax_id": "string",

"additional_info": "string",

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

"phone": {"country_code": "str",

"national_number": "string"

"fax": {"country_code": "str",

"national_number": "string"

}

schema/metadata.json Metadata

The audit metadata.


created_date	string<date-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.
cancelled_date	string<date-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.
last_updated_date	string<date-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.
first_sent_date	string<date-time> The date and time when the resource was first sent, in Internet date and time format.
last_sent_date	string<date-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.
payer_view_url	string<uri> The URL for the payer's view of the invoice.

Copy

`{"created_date": "2019-08-24T14:15:22Z",

"created_by": "string",

"cancelled_date": "2019-08-24T14:15:22Z",

"cancelled_by": "string",

"last_updated_date": "2019-08-24T14:15:22Z",

"last_updated_by": "string",

"first_sent_date": "2019-08-24T14:15:22Z",

"last_sent_date": "2019-08-24T14:15:22Z",

"last_sent_by": "string",

"payer_view_url": "http://example.com"

schema/notification.json Notification

The email or SMS notification.


subject	string The subject of the notification. Default is a generic subject.
note	string A note to the payer.
send_to_merchant	boolean Default:true Indicates whether to send a copy of the email to the merchant.
cc_emails	Array of strings<= 100 items An array of one or more CC: emails to which to send notification emails. If you omit this parameter, the API sends notification emails to all CC: email addresses that are part of the invoice. > Note: Valid values are email addresses in the `cc_info` array of the invoice.

Copy

Expand allCollapse all

`{"subject": "string",

"note": "string",

"send_to_merchant": true,

"cc_emails": ["string"

]

schema/participant.json Participant

The participant information.


email required	string<email><= 260 characters The email address of the person who receives a copy of the invoice.

Copy

`{"email": "user@example.com"

schema/payment-detail.json payment_detail

The payment details.


type	string The payment type in an invoicing flow. The record refund method supports the `EXTERNAL` refund type. The `PAYPAL` refund type is supported for backward compatibility. Enum:"PAYPAL""EXTERNAL"
transaction_id	string The ID for a PayPal payment transaction. Required for the `PAYPAL` payment type.
transaction_type	string The transaction type. Enum:"SALE""AUTHORIZATION""CAPTURE"
date	string<date-time> The date when the invoice was paid, in Internet date and time format.
method required	string The payment mode or method. Enum:"BANK_TRANSFER""CASH""CHECK""CREDIT_CARD""DEBIT_CARD""PAYPAL""WIRE_TRANSFER""OTHER"
note	string A note associated with the payment.
amount	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Copy

Expand allCollapse all

`{"type": "PAYPAL",

"transaction_id": "string",

"transaction_type": "SALE",

"date": "2019-08-24T14:15:22Z",

"method": "BANK_TRANSFER",

"note": "string",

"amount": {"currency": "string",

"value": "string"

}

schema/payment-summary.json payment_summary

The payment and refund summary.


paypal	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.
other	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Copy

Expand allCollapse all

`{"paypal": {"currency": "string",

"value": "string"

"other": {"currency": "string",

"value": "string"

}

schema/payment-term.json payment_term

The payment term of the invoice. If you specify term_type, you cannot specify due_date, and vice versa.


term_type	string The term when the invoice payment is due. Enum:"DUE_ON_RECEIPT""DUE_ON_DATE_SPECIFIED""NET_10""NET_15""NET_30""NET_45""NET_60""NET_90""NO_DUE_DATE"
due_date	string<date> The date when the invoice payment is due, in Internet date and time format. For example, yyyy- MM- dd z.

Copy

`{"term_type": "DUE_ON_RECEIPT",

"due_date": "2019-08-24"

schema/phone.json Phone

The phone number.


country_code	string[ 1 .. 3 ] characters^[0-9]{1,3}?$ The country code portion of the phone number, in E.164 format.
national_number	string[ 1 .. 14 ] characters^[0-9]{1,14}?$ The in-country phone number, in E.164 format.

Copy

`{"country_code": "str",

"national_number": "string"

schema/qr_code.json QR Code

The base64-encoded image of the image/png type.


image	string The base64-encoded image of the `image/png` type.

Copy

`{"image": "string"

schema/refund-detail.json refund_detail

The invoicing refund details.


type	string 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. The `PAYPAL` refund type is supported for backward compatibility. Enum:"PAYPAL""EXTERNAL"
transaction_id	string The ID of the PayPal refund transaction. Required for the `PAYPAL` refund type.
date	string<date-time> The date when the invoice was refunded, in Internet date and time format. For example, `2014-02-27 PST`.
note	string A note associated with the refund.
amount	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Copy

Expand allCollapse all

`{"type": "PAYPAL",

"transaction_id": "string",

"date": "2019-08-24T14:15:22Z",

"note": "string",

"amount": {"currency": "string",

"value": "string"

}

schema/search.json Search

The invoice search parameters.

The invoice status. To search by status, specify this value as an array. For example, "status": ["REFUNDED"]. The status indicates the phase of the invoice in its lifecycle:

Status	Occurs when
`CANCELLED`	A merchant or customer cancels a sent invoice.
`DRAFT`	A merchant creates a draft invoice. > Note: A customer cannot pay an invoice until a merchant sends it.
`MARKED_AS_PAID`	A merchant marks an invoice as paid after he or she receives a check or cash payment for the invoice.
`MARKED_AS_REFUNDED`	A merchant marks an invoice as refunded. > Note: A merchant can only mark a marked-as-paid invoice as refunded.
`PAID`	A customer fully pays an invoice. It is marked as paid through one or both of these methods: - A merchant marks an invoice as paid after he or she receives a check or cash payment from the customer for the invoice. - A customer makes an online payment for the invoice.
`PARTIALLY_PAID`	A merchant or customer fully pays an invoice through one or both of these methods: - A merchant marks an invoice as paid after he or she receives a check or cash payment from the customer for the invoice. - A customer makes an online payment for the invoice.
`PARTIALLY_REFUNDED`	A merchant partially refunds an invoice through one or both of these methods: - A merchant marks an invoice as refunded. To complete this action, the merchant must previously mark the invoice as paid. - A merchant makes an online refund for an online invoice payment.
`PAYMENT_PENDING`	A customer pays an invoice but the payment is pending for one of these reasons: - The payment is an uncleared eCheck. - The payment is in an accept or deny state upon which the merchant must act. - PayPal risk is reviewing the payment. > Note: Most payments never go into a payment-pending state.
`REFUNDED`	A merchant fully refunds an invoice through one or both of these methods: - A merchant marks an invoice as refunded. To complete this action, the merchant must previously mark the invoice as paid. - A merchant makes an online refund for an online invoice payment.
`SCHEDULED`	A merchant schedules an invoice to be emailed by PayPal on a specified date.
`SENT`	A merchant sends an invoice to the customer. After the merchant sends the invoice: - PayPal emails the invoice to the customer. - A Payment button appears on the invoice. The customer can now pay the invoice. - In a web app, the invoice appears as `Unpaid (sent)`.
`UNPAID`	A merchant sends an invoice and sets the `notify_merchant` and `notify_customer` query parameters to `false` to suppress the PayPal email notification. Then, the merchant manually sends the invoice link in his or her own email.

Copy

`{"email": "string",

"recipient_first_name": "string",

"recipient_last_name": "string",

"recipient_business_name": "string",

"number": "string",

"status": "DRAFT",

"lower_total_amount": "string",

"upper_total_amount": "string",

"start_invoice_date": "2019-08-24",

"end_invoice_date": "2019-08-24",

"start_due_date": "2019-08-24",

"end_due_date": "2019-08-24",

"start_payment_date": "2019-08-24",

"end_payment_date": "2019-08-24",

"start_creation_date": "2019-08-24",

"end_creation_date": "2019-08-24",

"page": 0,

"page_size": 0,

"total_count_required": false,

"archived": true

schema/shipping-cost.json shipping_cost

The shipping cost, as a percent or amount value.


amount	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.
tax	object (Tax) The tax information.

Copy

Expand allCollapse all

`{"amount": {"currency": "string",

"value": "string"

"tax": {"name": "string",

"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

schema/shipping-info.json shipping_info

The shipping information for the invoice recipient.


first_name	string<= 256 characters The first name of the recipient at the shipping address.
last_name	string<= 256 characters The last name of the recipient at the shipping address.
business_name	string<= 480 characters The business name of the recipient at the shipping address.
address	object (Address) The address, which is either a billing address or shipping address in a payment.

Copy

Expand allCollapse all

`{"first_name": "string",

"last_name": "string",

"business_name": "string",

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

}

schema/summary.json Summary

The summary of invoice data.

| status | string

The invoice status. The status indicates the phase of the invoice in its lifecycle:

Status	Occurs when
`CANCELLED`	A merchant or customer cancels a sent invoice.
`DRAFT`	A merchant creates a draft invoice. > Note: A customer cannot pay an invoice until a merchant sends it.
`MARKED_AS_PAID`	A merchant marks an invoice as paid after he or she receives a check or cash payment for the invoice.
`MARKED_AS_REFUNDED`	A merchant marks an invoice as refunded. > Note: A merchant can only mark a marked-as-paid invoice as refunded.
`PAID`	A customer fully pays an invoice. It is marked as paid through one or both of these methods: - A merchant marks an invoice as paid after he or she receives a check or cash payment from the customer for the invoice. - A customer makes an online payment for the invoice.
`PARTIALLY_PAID`	A merchant or customer fully pays an invoice through one or both of these methods: - A merchant marks an invoice as paid after he or she receives a check or cash payment from the customer for the invoice. - A customer makes an online payment for the invoice.
`PARTIALLY_REFUNDED`	A merchant partially refunds an invoice through one or both of these methods: - A merchant marks an invoice as refunded. To complete this action, the merchant must previously mark the invoice as paid. - A merchant makes an online refund for an online invoice payment.
`PAYMENT_PENDING`	A customer pays an invoice but the payment is pending for one of these reasons: - The payment is an uncleared eCheck. - The payment is in an accept or deny state upon which the merchant must act. - PayPal risk is reviewing the payment. > Note: Most payments never go into a payment-pending state.
`REFUNDED`	A merchant fully refunds an invoice through one or both of these methods: - A merchant marks an invoice as refunded. To complete this action, the merchant must previously mark the invoice as paid. - A merchant makes an online refund for an online invoice payment.
`SCHEDULED`	A merchant schedules an invoice to be emailed by PayPal on a specified date.
`SENT`	A merchant sends an invoice to the customer. After the merchant sends the invoice: - PayPal emails the invoice to the customer. - A Payment button appears on the invoice. The customer can now pay the invoice. - In a web app, the invoice appears as `Unpaid (sent)`.
`UNPAID`	A merchant sends an invoice and sets the `notify_merchant` and `notify_customer` query parameters to `false` to suppress the PayPal email notification. Then, the merchant manually sends the invoice link in his or her own email.

Enum:"DRAFT""SENT""SCHEDULED""PAID""MARKED_AS_PAID""CANCELLED""REFUNDED""PARTIALLY_REFUNDED""MARKED_AS_REFUNDED""UNPAID""PAYMENT_PENDING" | | count | integer
The total count of invoices. | | amount_summary | Array of objects (amount_summary)
An array of amounts, grouped by the currency code of the invoice. |

Copy

Expand allCollapse all

`{"status": "DRAFT",

"count": 0,

"amount_summary": [{"total_amount": {"currency": "string",

"value": "string"

},

"paid_amount": {"paypal": {"currency": "string",

"value": "string"

},

"other": {"currency": "string",

"value": "string"

}

},

"refunded_amount": {"paypal": {"currency": "string",

"value": "string"

},

"other": {"currency": "string",

"value": "string"

}

}

}

]

schema/tax.json Tax

The tax information.


name required	string<= 100 characters The tax name.
percent required	number>= 0 The tax rate. Value is from `0` to `100`. Supports up to five decimal places.
amount	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Copy

Expand allCollapse all

`{"name": "string",

"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

schema/template.json Template

The invoicing template.


template_id	string The ID of the template.
name	string The template name. > Note: The template name must be unique.
default	boolean Indicates whether this template is the default merchant template. A merchant can have one default template.
settings	Array of objects (template_settings) An array of template settings that describe which fields to show or hide when creating an invoice.
unit_of_measure	string The unit of measure for the template. Enum:"HOURS""QUANTITY""AMOUNT"
custom	boolean Indicates whether this template is a merchant-created custom template. The system generates non-custom templates.
links	Array of objects (Link Description) An array of request-related HATEOAS links.
template_data	object (template_data) The template data.

Copy

Expand allCollapse all

`{"template_id": "string",

"name": "string",

"default": true,

"settings": [{"field_name": "items.quantity",

"display_preference": {"hidden": false

}

}

],

"unit_of_measure": "HOURS",

"custom": true,

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"template_data": {"billing_info": [{"email": "user@example.com",

"first_name": "string",

"last_name": "string",

"business_name": "string",

"language": "da_DK",

"additional_info": "string",

"phone": {"country_code": "str",

"national_number": "string"

},

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

}

}

],

"cc_info": ["string"

],

"reference": "string",

"allow_partial_payment": false,

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"terms": "string",

"note": "string",

"merchant_memo": "string",

"logo_url": "http://example.com",

"attachments": [{"name": "string",

"url": "http://example.com"

}

],

"merchant_info": {"email": "user@example.com",

"business_name": "string",

"first_name": "string",

"last_name": "string",

"website": "http://example.com",

"tax_id": "string",

"additional_info": "string",

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

"phone": {"country_code": "str",

"national_number": "string"

"fax": {"country_code": "str",

"national_number": "string"

}

"shipping_info": {"first_name": "string",

"last_name": "string",

"business_name": "string",

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

}

"payment_term": {"term_type": "DUE_ON_RECEIPT",

"due_date": "2019-08-24"

"discount": {"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

"shipping_cost": {"amount": {"currency": "string",

"value": "string"

"tax": {"name": "string",

"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

"custom": {"label": "string",

"amount": {"currency": "string",

"value": "string"

}

"minimum_amount_due": {"currency": "string",

"value": "string"

"total_amount": {"currency": "string",

"value": "string"

}

schema/template-data.json template_data

The template data.


billing_info	Array of objects (billing_info) = 1 items The billing information of the invoice recipient. > Note: This value is an array with only one element.
cc_info	Array of strings<email> (Email) An array of email addresses to which PayPal sends a copy of the invoice.
items	Array of objects (invoice_item) <= 100 items An array of invoice line item information. The maximum items for an invoice is `100`.
reference	string<= 60 characters The reference data, such as a PO number.
allow_partial_payment	boolean Default:false Indicates whether the invoice allows a partial payment. If `false`, the invoice must be paid in full. If `true`, the invoice allows partial payments. > Note: This feature is not available for merchants in `India`, `Brazil`, or `Israel`.
tax_calculated_after_discount	boolean Default:false Indicates whether the tax is calculated before or after a discount. If `false`, the tax is calculated before a discount. If `true`, the tax is calculated after a discount.
tax_inclusive	boolean Default:false Indicates whether the unit price includes tax.
terms	string<= 4000 characters The general terms of the invoice.
note	string<= 4000 characters A note to the invoice recipient. This note also appears on the invoice notification email.
merchant_memo	string<= 150 characters A private bookkeeping memo for the merchant.
logo_url	string<uri><= 4000 characters The full URL to an external logo image. The logo image must not be larger than 250 pixels wide by 90 pixels high.
attachments	Array of objects (file_attachment) An array of PayPal file IDs for the files that are attached to an invoice. The maximum number of files is `5`.
merchant_info required	object (merchant_info) The merchant business information that appears on the invoice.
shipping_info	object (shipping_info) The shipping information for the invoice recipient.
payment_term	object (payment_term) The payment term of the invoice. If you specify `term_type`, you cannot specify `due_date`, and vice versa.
discount	object (Discount) The discount as a percent or an amount value. For example, to specify 10%, enter `10`. Alternatively, to specify an amount of 5, enter `5`.
shipping_cost	object (shipping_cost) The shipping cost, as a percent or amount value.
custom	object (custom_amount) The custom amount to apply to an invoice. If you include a label, you must include a custom amount.
minimum_amount_due	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.
total_amount	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Copy

Expand allCollapse all

`{"billing_info": [{"email": "user@example.com",

"first_name": "string",

"last_name": "string",

"business_name": "string",

"language": "da_DK",

"additional_info": "string",

"phone": {"country_code": "str",

"national_number": "string"

},

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

}

}

],

"cc_info": ["string"

],

"reference": "string",

"allow_partial_payment": false,

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"terms": "string",

"note": "string",

"merchant_memo": "string",

"logo_url": "http://example.com",

"attachments": [{"name": "string",

"url": "http://example.com"

}

],

"merchant_info": {"email": "user@example.com",

"business_name": "string",

"first_name": "string",

"last_name": "string",

"website": "http://example.com",

"tax_id": "string",

"additional_info": "string",

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

"phone": {"country_code": "str",

"national_number": "string"

"fax": {"country_code": "str",

"national_number": "string"

}

"shipping_info": {"first_name": "string",

"last_name": "string",

"business_name": "string",

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

}

"payment_term": {"term_type": "DUE_ON_RECEIPT",

"due_date": "2019-08-24"

"discount": {"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

"shipping_cost": {"amount": {"currency": "string",

"value": "string"

"tax": {"name": "string",

"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

"custom": {"label": "string",

"amount": {"currency": "string",

"value": "string"

}

"minimum_amount_due": {"currency": "string",

"value": "string"

"total_amount": {"currency": "string",

"value": "string"

}

schema/template-settings.json template_settings

The template settings.


field_name	string The field name in `template_data` for which to map corresponding display preferences. Enum:"items.quantity""items.description""items.date""items.discount""items.tax""discount""shipping""custom"
display_preference	object (template_settings_metadata) The template settings metadata.

Copy

Expand allCollapse all

`{"field_name": "items.quantity",

"display_preference": {"hidden": false

}

schema/template-settings-metadata.json template_settings_metadata

The template settings metadata.


hidden	boolean Default:false Indicates whether to show or hide this field.

Copy

`{"hidden": false

schema/templates.json Templates

A merchant-created template with associated details. The associated details include the emails, addresses, and phone numbers from the user's PayPal profile.


addresses	Array of objects (Address) An array of postal addresses in the user's PayPal profile.
emails	Array of strings An array of email addresses in the user's PayPal profile.
phones	Array of objects (Phone) An array of phone numbers in the user's PayPal profile.
templates	Array of objects (Template) The details for each template. If `fields` is `none`, returns only the template name, ID, and default status.
links	Array of objects (Link Description) An array of request-related HATEOAS links.

Copy

Expand allCollapse all

`{"addresses": [{"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

}

],

"emails": ["string"

],

"phones": [{"country_code": "str",

"national_number": "string"

}

],

"templates": [{"template_id": "string",

"name": "string",

"default": true,

"settings": [{"field_name": "items.quantity",

"display_preference": {"hidden": false

}

}

],

"unit_of_measure": "HOURS",

"custom": true,

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"template_data": {"billing_info": [{"email": "user@example.com",

"first_name": "string",

"last_name": "string",

"business_name": "string",

"language": "da_DK",

"additional_info": "string",

"phone": {"country_code": "str",

"national_number": "string"

},

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

}

}

],

"cc_info": ["string"

],

"items": [{"name": "string",

"description": "string",

"quantity": 0,

"date": "2019-08-24",

"unit_of_measure": "QUANTITY",

"unit_price": {"currency": "string",

"value": "string"

},

"tax": {"name": "string",

"percent": 0,

"amount": {"currency": null,

"value": null

}

},

"discount": {"percent": 0,

"amount": {"currency": null,

"value": null

}

}

}

],

"reference": "string",

"allow_partial_payment": false,

"tax_calculated_after_discount": false,

"tax_inclusive": false,

"terms": "string",

"note": "string",

"merchant_memo": "string",

"logo_url": "http://example.com",

"attachments": [{"name": "string",

"url": "http://example.com"

}

],

"merchant_info": {"email": "user@example.com",

"business_name": "string",

"first_name": "string",

"last_name": "string",

"website": "http://example.com",

"tax_id": "string",

"additional_info": "string",

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

},

"phone": {"country_code": "str",

"national_number": "string"

},

"fax": {"country_code": "str",

"national_number": "string"

}

},

"shipping_info": {"first_name": "string",

"last_name": "string",

"business_name": "string",

"address": {"line1": "string",

"line2": "string",

"city": "string",

"country_code": "string",

"postal_code": "string",

"state": "string",

"phone": "string"

}

},

"payment_term": {"term_type": "DUE_ON_RECEIPT",

"due_date": "2019-08-24"

},

"discount": {"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

},

"shipping_cost": {"amount": {"currency": "string",

"value": "string"

},

"tax": {"name": "string",

"percent": 0,

"amount": {"currency": "string",

"value": "string"

}

}

},

"custom": {"label": "string",

"amount": {"currency": "string",

"value": "string"

}

},

"minimum_amount_due": {"currency": "string",

"value": "string"

},

"total_amount": {"currency": "string",

"value": "string"

}

}

}

],

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

]

We currently use cookies to improve and customize your experience on our site. If you accept, we’ll also use marketing cookies to show you personalized ads. Manage your cookies and learn more.

Yes, I accept

Invoicing(1) ​

operation/invoice.create Create draft invoice ​

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

operation/invoice.get_all List invoices ​

query Parameters ​

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

operation/invoice.search Search for invoices ​

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

operation/invoice.send Send invoice ​

path Parameters ​

query Parameters ​

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

operation/invoice.schedule Schedule invoice ​

path Parameters ​

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

operation/invoice.remind Send invoice reminder ​

path Parameters ​

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

operation/invoice.cancel Cancel sent invoice ​

path Parameters ​

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

operation/invoice.record-payment Mark invoice as paid ​

path Parameters ​

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

operation/invoice.record-refund Mark invoice as refunded ​

path Parameters ​

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

operation/invoice.get Show invoice details ​

path Parameters ​

operation/invoice.update Update invoice ​

path Parameters ​

query Parameters ​

Request Body schema: application/json ​

operation/invoice.delete Delete draft invoice ​

path Parameters ​

operation/invoice.delete_external_payment Delete external payment ​

path Parameters ​

operation/invoice.delete_external_refund Delete external refund ​

path Parameters ​

operation/invoice.qr_code Generate QR code ​

path Parameters ​

query Parameters ​

operation/invoice.next_invoice_number Generate invoice number ​

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

operation/template.create Create template ​

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

operation/template.get_templates List templates ​

query Parameters ​

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

operation/template.get Show template details ​

path Parameters ​

operation/template.delete Delete template ​

path Parameters ​

operation/template.update Update template ​

path Parameters ​

Request Body schema: application/json ​

tag/Errors Errors ​

section/AUTHORIZATION_ERROR AUTHORIZATION_ERROR ​

section/BUSINESS_ERROR BUSINESS_ERROR ​

section/INTERNAL_SERVICE_ERROR INTERNAL_SERVICE_ERROR ​

section/MALFORMED_REQUEST_ERROR MALFORMED_REQUEST_ERROR ​

section/RESOURCE_NOT_FOUND_ERROR RESOURCE_NOT_FOUND_ERROR ​

section/UNKNOWN_ERROR UNKNOWN_ERROR ​

section/USER_BUSINESS_ERROR USER_BUSINESS_ERROR ​

section/VALIDATION_ERROR VALIDATION_ERROR ​

tag/Definitions Definitions ​

schema/common_components-v1-schema-json-openapi-2.0-address.json Address ​

schema/amount-summary.json amount_summary ​

schema/billing-info.json billing_info ​

schema/cancel-notification.json cancel_notification ​

schema/common_components-v1-schema-json-openapi-2.0-currency.json Currency ​

schema/custom-amount.json custom_amount ​

schema/discount.json Discount ​

schema/email.json Email ​

schema/common_components-v1-schema-json-openapi-2.0-error.json Error ​

schema/common_components-v1-schema-json-openapi-2.0-error_details.json Error Details ​

schema/file-attachment.json file_attachment ​

schema/invoice.json Invoice ​

schema/invoice_number.json Invoice Number ​

schema/invoice-item.json invoice_item ​

Invoicing(1)

operation/invoice.create Create draft invoice

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

operation/invoice.get_all List invoices

query Parameters

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

operation/invoice.search Search for invoices

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

operation/invoice.send Send invoice

path Parameters

query Parameters

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

operation/invoice.schedule Schedule invoice

path Parameters

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

operation/invoice.remind Send invoice reminder

path Parameters

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

operation/invoice.cancel Cancel sent invoice

path Parameters

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

operation/invoice.record-payment Mark invoice as paid

path Parameters

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

operation/invoice.record-refund Mark invoice as refunded

path Parameters

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

operation/invoice.get Show invoice details

path Parameters

operation/invoice.update Update invoice

path Parameters

query Parameters

Request Body schema: application/json

operation/invoice.delete Delete draft invoice

path Parameters

operation/invoice.delete_external_payment Delete external payment

path Parameters

operation/invoice.delete_external_refund Delete external refund

path Parameters

operation/invoice.qr_code Generate QR code

path Parameters

query Parameters

operation/invoice.next_invoice_number Generate invoice number

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

operation/template.create Create template

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

operation/template.get_templates List templates

query Parameters

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

operation/template.get Show template details

path Parameters

operation/template.delete Delete template

path Parameters

operation/template.update Update template

path Parameters

Request Body schema: application/json

tag/Errors Errors

section/AUTHORIZATION_ERROR AUTHORIZATION_ERROR

section/BUSINESS_ERROR BUSINESS_ERROR

section/INTERNAL_SERVICE_ERROR INTERNAL_SERVICE_ERROR

section/MALFORMED_REQUEST_ERROR MALFORMED_REQUEST_ERROR

section/RESOURCE_NOT_FOUND_ERROR RESOURCE_NOT_FOUND_ERROR

section/UNKNOWN_ERROR UNKNOWN_ERROR

section/USER_BUSINESS_ERROR USER_BUSINESS_ERROR

section/VALIDATION_ERROR VALIDATION_ERROR

tag/Definitions Definitions

schema/common_components-v1-schema-json-openapi-2.0-address.json Address

schema/amount-summary.json amount_summary

schema/billing-info.json billing_info

schema/cancel-notification.json cancel_notification

schema/common_components-v1-schema-json-openapi-2.0-currency.json Currency

schema/custom-amount.json custom_amount

schema/discount.json Discount

schema/email.json Email

schema/common_components-v1-schema-json-openapi-2.0-error.json Error

schema/common_components-v1-schema-json-openapi-2.0-error_details.json Error Details

schema/file-attachment.json file_attachment

schema/invoice.json Invoice

schema/invoice_number.json Invoice Number

schema/invoice-item.json invoice_item