Invoicing API
Deprecation notice: TheUse 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./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Invoices (resource group)
Use the /invoices
resource to create, update, and send invoices and invoice reminders. To manage invoices, you can also list invoices, show details for invoices, delete draft invoices, and cancel sent invoices. You can also mark invoices as fully or partially paid, or as refunded. Lastly, you can create QR codes for invoices that can be scanned, viewed, and paid by a mobile phone.
List invoices
Deprecation notice: TheLists invoices. To filter the invoices that appear in the response, you can specify one or more optional query parameters./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Query parameters
page
integer
The zero-relative start index of the entire list of merchant invoices that are returned in the response. So, the combination of
page=0
andpage_size=20
returns the first 20 invoices. The combination ofpage=20
andpage_size=20
returns the next 20 invoices.page_size
integer
The number of invoices to return in the response.
total_count_required
boolean
Indicates whether to show the total count in the response.
Response
A successful request returns the HTTP 200 OK
status code and a JSON response body that lists invoices with details.
total_count
integer
The total number of invoices that match the search criteria.
invoices
array (contains the invoice object)
An array of invoice-level details.
Note: This array does not return item details for the invoice.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"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.sandbox.paypal.com/v1/invoicing/invoices?page=4&page_size=4&total_count_required=true",
"rel": "next",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/invoicing/invoices?page=2&page_size=4&total_count_required=true",
"rel": "previous",
"method": "GET"
}
]
}
Create draft invoice
Deprecation notice: TheCreates a draft invoice. To move the invoice from a draft to payable state, you must send the invoice./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
In the JSON request body, include invoice details including merchant information. The
invoice
object must include an items
array.Note: The merchant that you specify in an invoice must have a PayPal account in good standing..
Request body
id
string
The ID of the invoice.
number
string
The invoice number. If you omit this value, the default is the number that the API automatically increments from the last number.
status
enum
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
orUNPAID
.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
andnotify_customer
query parameters tofalse
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
orUNPAID
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:
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.
The merchant information, such as business name, email, address, and so on.
billing_info
array (contains the billing_info object)
An array of billing information for the invoice recipient.
Note: This value is an array with only one element.
shipping_info
The shipping information for the recipient of the invoice.
cc_info
array (contains the participant object)
An array of email addresses to which PayPal sends a copy of the invoice.
items
array (contains the invoice_item object)
An array of invoice line item information.
invoice_date
string
The invoice date as specified by the sender, in Internet date and time format.
payment_term
The payment due date of the invoice. If you include
due_date
, theterm_type
value is ignored.reference
string
The reference data, such as PO number.
discount
The invoice level discount, as a percent or an amount value.
shipping_cost
The shipping amount, as a percent or an amount value.
custom
The custom amount to apply to an invoice. If you include a label, you must include a custom amount.
allow_partial_payment
boolean
Indicates whether the invoice allows a partial payment. If
false
, the invoice must be paid in full. Iftrue
, the invoice allows partial payments.Note: This feature is not available for merchants in
India
,Brazil
, orIsrael
.minimum_amount_due
The minimum amount allowed for a partial payment. Valid only if
allow_partial_payment
istrue
.tax_calculated_after_discount
boolean
Indicates whether the tax is calculated before or after a discount. If
false
, the tax is calculated before a discount. Iftrue
, the tax is calculated after a discount.tax_inclusive
boolean
Indicates whether the unit price includes tax.
terms
string
The general terms of the invoice.
note
string
A note to the invoice recipient. The note also appears on the invoice notification email.
merchant_memo
string
A private bookkeeping memo for the merchant.
logo_url
string
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.
total_amount
The total amount of the invoice.
payments
array (contains the payment_detail object)
An array of payment details for the invoice.
refunds
array (contains the refund_detail object)
An array of refund details for the invoice.
metadata
The audit information for the invoice.
paid_amount
The payment summary of the invoice. Includes the amount paid through PayPal and other sources.
refunded_amount
The payment summary of the invoice. Includes the amount refunded through PayPal and other sources.
attachments
array (contains the file_attachment object)
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
Indicates whether the invoice enables the customer to enter a tip amount during payment. If
true
, the invoice shows a tip amount field so that the customer can enter a tip amount. Iffalse
, the invoice does not show a tip amount field.Note: This feature is not available for merchants in
Hong Kong
,Taiwan
,India
, orJapan
.template_id
string
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 (contains the link_description object)
An array of request-related HATEOAS links.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"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
A successful request returns the HTTP 201 Created
status code and a JSON response body that shows invoice details.
id
string
The ID of the invoice.
number
string
The invoice number. If you omit this value, the default is the number that the API automatically increments from the last number.
status
enum
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
orUNPAID
.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
andnotify_customer
query parameters tofalse
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
orUNPAID
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:
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.
merchant_info
The merchant information, such as business name, email, address, and so on.
billing_info
array (contains the billing_info object)
An array of billing information for the invoice recipient.
Note: This value is an array with only one element.
shipping_info
The shipping information for the recipient of the invoice.
cc_info
array (contains the participant object)
An array of email addresses to which PayPal sends a copy of the invoice.
items
array (contains the invoice_item object)
An array of invoice line item information.
invoice_date
string
The invoice date as specified by the sender, in Internet date and time format.
payment_term
The payment due date of the invoice. If you include
due_date
, theterm_type
value is ignored.reference
string
The reference data, such as PO number.
discount
The invoice level discount, as a percent or an amount value.
shipping_cost
The shipping amount, as a percent or an amount value.
custom
The custom amount to apply to an invoice. If you include a label, you must include a custom amount.
allow_partial_payment
boolean
Indicates whether the invoice allows a partial payment. If
false
, the invoice must be paid in full. Iftrue
, the invoice allows partial payments.Note: This feature is not available for merchants in
India
,Brazil
, orIsrael
.minimum_amount_due
The minimum amount allowed for a partial payment. Valid only if
allow_partial_payment
istrue
.tax_calculated_after_discount
boolean
Indicates whether the tax is calculated before or after a discount. If
false
, the tax is calculated before a discount. Iftrue
, the tax is calculated after a discount.tax_inclusive
boolean
Indicates whether the unit price includes tax.
terms
string
The general terms of the invoice.
note
string
A note to the invoice recipient. The note also appears on the invoice notification email.
merchant_memo
string
A private bookkeeping memo for the merchant.
logo_url
string
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.
total_amount
The total amount of the invoice.
payments
array (contains the payment_detail object)
An array of payment details for the invoice.
refunds
array (contains the refund_detail object)
An array of refund details for the invoice.
metadata
The audit information for the invoice.
paid_amount
The payment summary of the invoice. Includes the amount paid through PayPal and other sources.
refunded_amount
The payment summary of the invoice. Includes the amount refunded through PayPal and other sources.
attachments
array (contains the file_attachment object)
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
Indicates whether the invoice enables the customer to enter a tip amount during payment. If
true
, the invoice shows a tip amount field so that the customer can enter a tip amount. Iffalse
, the invoice does not show a tip amount field.Note: This feature is not available for merchants in
Hong Kong
,Taiwan
,India
, orJapan
.template_id
string
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 (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"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.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX",
"method": "GET"
},
{
"rel": "send",
"href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX/send",
"method": "POST"
},
{
"rel": "update",
"href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX",
"method": "PUT"
},
{
"rel": "delete",
"href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX",
"method": "DELETE"
}
]
}
Delete draft invoice
Deprecation notice: TheDeletes invoices in the/v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
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.Path parameters
invoice_id
string
required
The ID of the draft invoice to delete.
Response
A successful request returns the HTTP 204 No Content
status code with no JSON response body.
Sample Response
204 No Content
Update invoice
Deprecation notice: TheFully updates an invoice, by ID. In the JSON request body, include a complete `invoice` object. This call does not support partial updates./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Query parameters
notify_merchant
boolean
Indicates whether to send the invoice update notification to the merchant.
Path parameters
invoice_id
string
required
The ID of the invoice to update.
Request body
id
string
The ID of the invoice.
number
string
The invoice number. If you omit this value, the default is the number that the API automatically increments from the last number.
status
enum
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
orUNPAID
.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
andnotify_customer
query parameters tofalse
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
orUNPAID
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:
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.
The merchant information, such as business name, email, address, and so on.
billing_info
array (contains the billing_info object)
An array of billing information for the invoice recipient.
Note: This value is an array with only one element.
shipping_info
The shipping information for the recipient of the invoice.
cc_info
array (contains the participant object)
An array of email addresses to which PayPal sends a copy of the invoice.
items
array (contains the invoice_item object)
An array of invoice line item information.
invoice_date
string
The invoice date as specified by the sender, in Internet date and time format.
payment_term
The payment due date of the invoice. If you include
due_date
, theterm_type
value is ignored.reference
string
The reference data, such as PO number.
discount
The invoice level discount, as a percent or an amount value.
shipping_cost
The shipping amount, as a percent or an amount value.
custom
The custom amount to apply to an invoice. If you include a label, you must include a custom amount.
allow_partial_payment
boolean
Indicates whether the invoice allows a partial payment. If
false
, the invoice must be paid in full. Iftrue
, the invoice allows partial payments.Note: This feature is not available for merchants in
India
,Brazil
, orIsrael
.minimum_amount_due
The minimum amount allowed for a partial payment. Valid only if
allow_partial_payment
istrue
.tax_calculated_after_discount
boolean
Indicates whether the tax is calculated before or after a discount. If
false
, the tax is calculated before a discount. Iftrue
, the tax is calculated after a discount.tax_inclusive
boolean
Indicates whether the unit price includes tax.
terms
string
The general terms of the invoice.
note
string
A note to the invoice recipient. The note also appears on the invoice notification email.
merchant_memo
string
A private bookkeeping memo for the merchant.
logo_url
string
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.
total_amount
The total amount of the invoice.
payments
array (contains the payment_detail object)
An array of payment details for the invoice.
refunds
array (contains the refund_detail object)
An array of refund details for the invoice.
metadata
The audit information for the invoice.
paid_amount
The payment summary of the invoice. Includes the amount paid through PayPal and other sources.
refunded_amount
The payment summary of the invoice. Includes the amount refunded through PayPal and other sources.
attachments
array (contains the file_attachment object)
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
Indicates whether the invoice enables the customer to enter a tip amount during payment. If
true
, the invoice shows a tip amount field so that the customer can enter a tip amount. Iffalse
, the invoice does not show a tip amount field.Note: This feature is not available for merchants in
Hong Kong
,Taiwan
,India
, orJapan
.template_id
string
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 (contains the link_description object)
An array of request-related HATEOAS links.
Sample Request
curl -v -X PUT https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-8UZ6-Q3DK-VZXV-SXQB \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"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
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows invoice details.
id
string
The ID of the invoice.
number
string
The invoice number. If you omit this value, the default is the number that the API automatically increments from the last number.
status
enum
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
orUNPAID
.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
andnotify_customer
query parameters tofalse
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
orUNPAID
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:
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.
merchant_info
The merchant information, such as business name, email, address, and so on.
billing_info
array (contains the billing_info object)
An array of billing information for the invoice recipient.
Note: This value is an array with only one element.
shipping_info
The shipping information for the recipient of the invoice.
cc_info
array (contains the participant object)
An array of email addresses to which PayPal sends a copy of the invoice.
items
array (contains the invoice_item object)
An array of invoice line item information.
invoice_date
string
The invoice date as specified by the sender, in Internet date and time format.
payment_term
The payment due date of the invoice. If you include
due_date
, theterm_type
value is ignored.reference
string
The reference data, such as PO number.
discount
The invoice level discount, as a percent or an amount value.
shipping_cost
The shipping amount, as a percent or an amount value.
custom
The custom amount to apply to an invoice. If you include a label, you must include a custom amount.
allow_partial_payment
boolean
Indicates whether the invoice allows a partial payment. If
false
, the invoice must be paid in full. Iftrue
, the invoice allows partial payments.Note: This feature is not available for merchants in
India
,Brazil
, orIsrael
.minimum_amount_due
The minimum amount allowed for a partial payment. Valid only if
allow_partial_payment
istrue
.tax_calculated_after_discount
boolean
Indicates whether the tax is calculated before or after a discount. If
false
, the tax is calculated before a discount. Iftrue
, the tax is calculated after a discount.tax_inclusive
boolean
Indicates whether the unit price includes tax.
terms
string
The general terms of the invoice.
note
string
A note to the invoice recipient. The note also appears on the invoice notification email.
merchant_memo
string
A private bookkeeping memo for the merchant.
logo_url
string
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.
total_amount
The total amount of the invoice.
payments
array (contains the payment_detail object)
An array of payment details for the invoice.
refunds
array (contains the refund_detail object)
An array of refund details for the invoice.
metadata
The audit information for the invoice.
paid_amount
The payment summary of the invoice. Includes the amount paid through PayPal and other sources.
refunded_amount
The payment summary of the invoice. Includes the amount refunded through PayPal and other sources.
attachments
array (contains the file_attachment object)
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
Indicates whether the invoice enables the customer to enter a tip amount during payment. If
true
, the invoice shows a tip amount field so that the customer can enter a tip amount. Iffalse
, the invoice does not show a tip amount field.Note: This feature is not available for merchants in
Hong Kong
,Taiwan
,India
, orJapan
.template_id
string
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 (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"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"
}
}
Show invoice details
Deprecation notice: TheShows details for an invoice, by ID./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Path parameters
invoice_id
string
required
The ID of the invoice for which to show details.
Response
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows invoice details.
id
string
The ID of the invoice.
number
string
The invoice number. If you omit this value, the default is the number that the API automatically increments from the last number.
status
enum
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
orUNPAID
.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
andnotify_customer
query parameters tofalse
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
orUNPAID
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:
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.
merchant_info
The merchant information, such as business name, email, address, and so on.
billing_info
array (contains the billing_info object)
An array of billing information for the invoice recipient.
Note: This value is an array with only one element.
shipping_info
The shipping information for the recipient of the invoice.
cc_info
array (contains the participant object)
An array of email addresses to which PayPal sends a copy of the invoice.
items
array (contains the invoice_item object)
An array of invoice line item information.
invoice_date
string
The invoice date as specified by the sender, in Internet date and time format.
payment_term
The payment due date of the invoice. If you include
due_date
, theterm_type
value is ignored.reference
string
The reference data, such as PO number.
discount
The invoice level discount, as a percent or an amount value.
shipping_cost
The shipping amount, as a percent or an amount value.
custom
The custom amount to apply to an invoice. If you include a label, you must include a custom amount.
allow_partial_payment
boolean
Indicates whether the invoice allows a partial payment. If
false
, the invoice must be paid in full. Iftrue
, the invoice allows partial payments.Note: This feature is not available for merchants in
India
,Brazil
, orIsrael
.minimum_amount_due
The minimum amount allowed for a partial payment. Valid only if
allow_partial_payment
istrue
.tax_calculated_after_discount
boolean
Indicates whether the tax is calculated before or after a discount. If
false
, the tax is calculated before a discount. Iftrue
, the tax is calculated after a discount.tax_inclusive
boolean
Indicates whether the unit price includes tax.
terms
string
The general terms of the invoice.
note
string
A note to the invoice recipient. The note also appears on the invoice notification email.
merchant_memo
string
A private bookkeeping memo for the merchant.
logo_url
string
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.
total_amount
The total amount of the invoice.
payments
array (contains the payment_detail object)
An array of payment details for the invoice.
refunds
array (contains the refund_detail object)
An array of refund details for the invoice.
metadata
The audit information for the invoice.
paid_amount
The payment summary of the invoice. Includes the amount paid through PayPal and other sources.
refunded_amount
The payment summary of the invoice. Includes the amount refunded through PayPal and other sources.
attachments
array (contains the file_attachment object)
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
Indicates whether the invoice enables the customer to enter a tip amount during payment. If
true
, the invoice shows a tip amount field so that the customer can enter a tip amount. Iffalse
, the invoice does not show a tip amount field.Note: This feature is not available for merchants in
Hong Kong
,Taiwan
,India
, orJapan
.template_id
string
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 (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"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.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7/send",
"rel": "send",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7",
"rel": "delete",
"method": "DELETE"
},
{
"href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7",
"rel": "update",
"method": "PUT"
}
]
}
Cancel sent invoice
Deprecation notice: TheCancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and CC: emails./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Path parameters
invoice_id
string
required
The ID of the invoice to cancel.
Request body
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
Indicates whether to send the notification to the merchant.
send_to_payer
boolean
Indicates whether to send the notification to the payer.
cc_emails
array (contains the cc_email object)
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.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-WW57-VFCD-X5H4-XTUP/cancel \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"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
A successful request returns the HTTP 204 No Content
status code with no JSON response body.
Sample Response
204 No Content
Delete external payment
Deprecation notice: TheDeletes an external payment, by invoice ID and transaction ID./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Path parameters
invoice_id
string
required
The ID of the invoice from which to delete an external payment transaction.
transaction_id
string
required
The ID of the external payment transaction to delete.
Sample Request
curl -v -X DELETE https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-TBRZ-SWBK-7FQ9-AC8F/payment-records/EXTR-86F38350LX4353815 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
A successful request returns the HTTP 204 No Content
status code with no JSON response body.
Sample Response
204 No Content
Generate QR code
Deprecation notice: TheGenerates 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./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Query parameters
width
integer
The width, in pixels, of the QR code image. Value is from
150
to500
.height
integer
The height, in pixels, of the QR code image. Value is from
150
to500
.
Path parameters
invoice_id
string
required
The ID of the invoice for which to generate a QR code.
Response
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows the QR code as a PNG image.
image
string
The base64-encoded image of the
image/png
type.
Sample Response
{
"image": "iVBORw0KGgoAA......XUDM"
}
Mark invoice as paid
Deprecation notice: TheMarks the status of an invoice, by ID, as paid./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Path parameters
invoice_id
string
required
The ID of the invoice to mark as paid.
Request body
type
enum
The payment type in an invoicing flow. The record refund method supports the
EXTERNAL
refund type. ThePAYPAL
refund type is supported for backward compatibility.transaction_id
string
The ID for a PayPal payment transaction. Required for the
PAYPAL
payment type.transaction_type
enum
The transaction type.
date
string
The date when the invoice was paid, in Internet date and time format.
method
enum
required
The payment mode or method.
note
string
A note associated with the payment.
amount
The payment amount to record against the invoice. If you omit this parameter, the total invoice amount is marked as paid. This amount cannot exceed the amount due.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-T4UQ-VW4W-K7N7-XM2R/record-payment \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"method": "CASH",
"date": "2013-11-06 03:30:00 PST",
"note": "I got the payment by cash!",
"amount": {
"currency": "USD",
"value": "20.00"
}
}'
Response
A successful request returns the HTTP 200 OK
status code with no JSON response body.
Sample Response
200 OK
Mark invoice as refunded
Deprecation notice: TheMarks the status of an invoice, by ID, as refunded./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Path parameters
invoice_id
string
required
The ID of the invoice to mark as refunded.
Request body
type
enum
The PayPal refund type. Indicates whether the refund was paid through PayPal or externally in the invoicing flow. The record refund method supports the
EXTERNAL
refund type. ThePAYPAL
refund type is supported for backward compatibility.transaction_id
string
The ID of the PayPal refund transaction. Required for the
PAYPAL
refund type.date
string
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
The currency and amount to record as refunded. If you omit the amount, the total invoice paid amount is recorded as refunded.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-T4UQ-VW4W-K7N7-XM2R/record-refund \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"date": "2013-11-10 14:00:00 PST",
"note": "Refunded by cash!",
"amount": {
"currency": "USD",
"value": "20.00"
}
}'
Response
A successful request returns the HTTP 200 OK
status code with no JSON response body.
Sample Response
200 OK
Delete external refund
Deprecation notice: TheDeletes an external refund, by invoice ID and transaction ID./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Path parameters
invoice_id
string
required
The ID of the invoice from which to delete the external refund transaction.
transaction_id
string
required
The ID of the external refund transaction to delete.
Sample Request
curl -v -X DELETE https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-333R-YUQL-YNNN-D7WF/refund-records/EXTR-2LG703375E477444T \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
A successful request returns the HTTP 204 No Content
status code with no JSON response body.
Sample Response
204 No Content
Send invoice reminder
Deprecation notice: TheSends 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./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Path parameters
invoice_id
string
required
The ID of the invoice for which to send a reminder.
Request body
subject
string
The subject of the notification. Default is a generic subject.
note
string
A note to the payer.
send_to_merchant
boolean
Indicates whether to send a copy of the email to the merchant.
cc_emails
array (contains the cc_email object)
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.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-T4UQ-VW4W-K7N7-XM2R/remind \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"subject": "Past due",
"note": "Please pay soon",
"send_to_merchant": true,
"cc_emails": [
"cc-email@example.com"
]
}'
Response
A successful request returns the HTTP 202 Accepted
status code with no JSON response body.
Sample Response
202 Accepted
Schedule invoice
Deprecation notice: TheSchedules 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/v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
SENT
.Note: To change the scheduled date, adjust the invoice date and update invoice. To send the invoice immediately, update the invoice date to today or to a date in the past.
Path parameters
invoice_id
string
required
The ID of the invoice to schedule.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-EHNV-LJ5S-A7DZ-V6NJ/schedule \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
A successful request returns the HTTP 202 Accepted
status code and a JSON response body with a link to the invoice .
Sample Response
{
"links": [
{
"href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7",
"rel": "self",
"method": "GET"
}
]
}
Send invoice
Deprecation notice: TheSends an invoice, by ID, to a customer. To suppress the merchant's email notification, set the `notify_merchant` query parameter to `false`./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Note: After you send an invoice, you cannot resend it.
Query parameters
notify_merchant
boolean
Indicates whether to send the invoice update notification to the merchant.
Path parameters
invoice_id
string
required
The ID of the invoice to send.
Response
A successful request returns the HTTP 202 Accepted
status code with no JSON response body.
Sample Response
202 Accepted
Generate invoice number
Deprecation notice: TheGenerates 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`./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/next-invoice-number \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows the next 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.
Sample Request
{
"number": "ee0044"
}
Sample Response
{
"number": "ee0044"
}
Templates (resource group)
Use the /templates
resource to create, list, show details for, update, and delete invoice templates. The template API is useful when creating a third-party invoicing application. For instance, a business can create a template with predefined invoice data. Later, the business can select the template to populate the invoice data.
Note: To upload a logo to display on an invoice, you can use the Template Settings dashboard to create a template. Then, use the URI of that logo when you create an invoice.
List templates
Deprecation notice: TheLists merchant-created templates with associated details. The associated details include the email addresses, postal addresses, and phone numbers from the user's PayPal profile./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
The user can select which values to show in the business information section of their template.
Query parameters
fields
string
The fields to return in the response. Value is
all
ornone
. To return only the template name, ID, and default attributes, specifynone
.
Sample Request
curl -v -X GET https://api.sandbox.paypal.com/v1/invoicing/templates \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
A successful request returns the HTTP 200 OK
status code and a JSON response body that lists invoices.
addresses
array (contains the address object)
An array of postal addresses in the user's PayPal profile.
emails
array (contains the email object)
An array of email addresses in the user's PayPal profile.
phones
array (contains the phone object)
An array of phone numbers in the user's PayPal profile.
templates
array (contains the template object)
The details for each template. If
fields
isnone
, returns only the template name, ID, and default status.links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"addresses": [
{
"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.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
"rel": "replace",
"method": "PUT"
},
{
"href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
"rel": "delete",
"method": "DELETE"
}
]
}
],
"links": [
{
"href": "https://api.sandbox.paypal.com/v1/invoicing/templates",
"rel": "collection",
"method": "GET"
}
]
}
Create template
Deprecation notice: TheCreates an invoice template. You can use details from this template to create an invoice. You can create up to 50 templates./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Note: Every merchant starts with three PayPal system templates that are optimized for the unit type billed. The template includes `Quantity`, `Hours`, and `Amount`.
Request body
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.
template_data
The template data.
settings
array (contains the template_settings object)
An array of template settings that describe which fields to show or hide when creating an invoice.
unit_of_measure
enum
The unit of measure for the template.
custom
boolean
Indicates whether this template is a merchant-created custom template. The system generates non-custom templates.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/templates/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"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
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows template details.
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.
template_data
The template data.
settings
array (contains the template_settings object)
An array of template settings that describe which fields to show or hide when creating an invoice.
unit_of_measure
enum
The unit of measure for the template.
custom
boolean
Indicates whether this template is a merchant-created custom template. The system generates non-custom templates.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"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.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
"rel": "replace",
"method": "PUT"
},
{
"href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
"rel": "delete",
"method": "DELETE"
}
]
}
Delete template
Path parameters
template_id
string
required
The ID of the template to delete.
Sample Request
curl -v -X DELETE https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-0JV3858360943364J \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
A successful request returns the HTTP 204 No Content
status code with no JSON response body.
Sample Response
204 No Content
Update template
Deprecation notice: TheUpdates a template, by ID. In the JSON request body, specify a complete `template` object. The update method does not support partial updates./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Path parameters
template_id
string
required
The ID of the template to update.
Request body
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.
template_data
The template data.
settings
array (contains the template_settings object)
An array of template settings that describe which fields to show or hide when creating an invoice.
unit_of_measure
enum
The unit of measure for the template.
custom
boolean
Indicates whether this template is a merchant-created custom template. The system generates non-custom templates.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Request
curl -v -X PUT https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"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
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows template details.
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.
template_data
The template data.
settings
array (contains the template_settings object)
An array of template settings that describe which fields to show or hide when creating an invoice.
unit_of_measure
enum
The unit of measure for the template.
custom
boolean
Indicates whether this template is a merchant-created custom template. The system generates non-custom templates.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"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.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
"rel": "replace",
"method": "PUT"
},
{
"href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
"rel": "delete",
"method": "DELETE"
}
]
}
Show template details
Deprecation notice: TheShows details for a template, by ID./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Path parameters
template_id
string
required
The ID of the template for which to show details.
Sample Request
curl -v -X GET https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-0JV3858360943364J \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows template details.
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.
template_data
The template data.
settings
array (contains the template_settings object)
An array of template settings that describe which fields to show or hide when creating an invoice.
unit_of_measure
enum
The unit of measure for the template.
custom
boolean
Indicates whether this template is a merchant-created custom template. The system generates non-custom templates.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"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.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
"rel": "replace",
"method": "PUT"
},
{
"href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
"rel": "delete",
"method": "DELETE"
}
]
}
Search (resource group)
Use the /search
resource to search for invoices.
Search for invoices
Deprecation notice: TheSearches for invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria./v1/invoices
endpoint is deprecated. Use the/v2/invoices
endpoint instead. For details, see PayPal Invoicing Basic Integration.
Request body
email
string
The initial letters of the email address.
recipient_first_name
string
The initial letters of the recipient's first name.
recipient_last_name
string
The initial letters of the recipient's last name.
recipient_business_name
string
The initial letters of the recipient's business name.
number
string
Any part of the invoice number.
status
enum
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
andnotify_customer
query parameters tofalse
to suppress the PayPal email notification. Then, the merchant manually sends the invoice link in his or her own email.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
The start date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
end_invoice_date
string
The end date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
start_due_date
string
The start due date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
end_due_date
string
The end due date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
start_payment_date
string
The start payment date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
end_payment_date
string
The end payment date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
start_creation_date
string
The start creation date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
end_creation_date
string
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
andpage_size=20
returns the first 20 invoices. A combination ofpage=20
andpage_size=20
returns the next 20 invoices.page_size
number
The page size for the search results.
total_count_required
boolean
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. Iffalse
, response lists only unarchived invoices. Ifnull
, response lists all invoices.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/search/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"start_invoice_date": "2014-01-01 PST",
"end_invoice_date": "2014-03-26 PST",
"page": 0,
"page_size": 3,
"total_count_required": true
}'
Response
A successful request returns the HTTP 200 OK
status code and a JSON response body that lists the invoices that match the search criteria.
total_count
integer
The total number of invoices that match the search criteria.
invoices
array (contains the invoice object)
An array of invoice-level details.
Note: This array does not return item details for the invoice.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"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"
}
}
]
}
Common object definitions
address
line1
string
required
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
string
required
The city name.
country_code
string
required
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GB
and notUK
as is used in that country's top-level domain names. Use theC2
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
phone
string
The phone number, in its canonical international E.164 numbering plan format.
address_postal_code_validation
address_postal_code_validation
amount_summary
billing_info
email
string
The invoice recipient email address. If you omit this value, the invoice is payable and a notification email is not sent.
phone
The invoice recipient's phone number.
first_name
string
The invoice recipient's first name.
last_name
string
The invoice recipient's last name.
business_name
string
The invoice recipient's business name.
address
The invoice recipient's billing address.
language
enum
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.additional_info
string
Any additional information about the recipient.
cancel_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
Indicates whether to send the notification to the merchant.
send_to_payer
boolean
Indicates whether to send the notification to the payer.
cc_emails
array (contains the cc_email object)
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.
cc_email
cc_email
string
A CC: email to which to send a notification email.
currency
currency
string
required
value
string
required
The value, which might be:
- An integer for currencies like
JPY
that are not typically fractional. - A decimal fraction for currencies like
TND
that are subdivided into thousandths.
- An integer for currencies like
custom_amount
label
string
The custom amount label.
amount
The currency and amount of the custom value. Value is from
-1000000
to1000000
. Supports up to two decimal places.
discount
percent
number
The discount as a percentage value. Value is from
0
to100
. Supports up to five decimal places.amount
The currency and amount of the invoice-level discount. Value is from
0
to1000000
. Supports up to two decimal places.
email
string
An email in the user's PayPal profile.
email
string
The participant's email address.
error
name
string
required
The human-readable, unique name of the error.
debug_id
string
The PayPal internal ID. Used for correlation purposes.
message
string
required
The message that describes the error.
information_link
string
required
The URI to detailed information related to this error for the developer.
details
array (contains the error_details object)
An array of additional details for the error.
error_details
field
string
required
The name of the field that caused the error.
issue
string
required
The reason for the error.
file_attachment
name
string
The name of the attached file.
url
string
The URL of the attached file. Use this URL to download the file.
file_upload_response
message
string
The Document Management System (DMS) information.
id
string
The encrypted DMS-returned path for invoices.
filename
string
The file name of the uploaded document.
group_invoicing_response
group_id
string
required
The ID for the group of invoices.
invoice
id
string
The ID of the invoice.
number
string
The invoice number. If you omit this value, the default is the number that the API automatically increments from the last number.
status
enum
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
orUNPAID
.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
andnotify_customer
query parameters tofalse
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
orUNPAID
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:
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.
The merchant information, such as business name, email, address, and so on.
billing_info
array (contains the billing_info object)
An array of billing information for the invoice recipient.
Note: This value is an array with only one element.
shipping_info
The shipping information for the recipient of the invoice.
cc_info
array (contains the participant object)
An array of email addresses to which PayPal sends a copy of the invoice.
items
array (contains the invoice_item object)
An array of invoice line item information.
invoice_date
string
The invoice date as specified by the sender, in Internet date and time format.
payment_term
The payment due date of the invoice. If you include
due_date
, theterm_type
value is ignored.reference
string
The reference data, such as PO number.
discount
The invoice level discount, as a percent or an amount value.
shipping_cost
The shipping amount, as a percent or an amount value.
custom
The custom amount to apply to an invoice. If you include a label, you must include a custom amount.
allow_partial_payment
boolean
Indicates whether the invoice allows a partial payment. If
false
, the invoice must be paid in full. Iftrue
, the invoice allows partial payments.Note: This feature is not available for merchants in
India
,Brazil
, orIsrael
.minimum_amount_due
The minimum amount allowed for a partial payment. Valid only if
allow_partial_payment
istrue
.tax_calculated_after_discount
boolean
Indicates whether the tax is calculated before or after a discount. If
false
, the tax is calculated before a discount. Iftrue
, the tax is calculated after a discount.tax_inclusive
boolean
Indicates whether the unit price includes tax.
terms
string
The general terms of the invoice.
note
string
A note to the invoice recipient. The note also appears on the invoice notification email.
merchant_memo
string
A private bookkeeping memo for the merchant.
logo_url
string
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.
total_amount
The total amount of the invoice.
payments
array (contains the payment_detail object)
An array of payment details for the invoice.
refunds
array (contains the refund_detail object)
An array of refund details for the invoice.
metadata
The audit information for the invoice.
paid_amount
The payment summary of the invoice. Includes the amount paid through PayPal and other sources.
refunded_amount
The payment summary of the invoice. Includes the amount refunded through PayPal and other sources.
attachments
array (contains the file_attachment object)
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
Indicates whether the invoice enables the customer to enter a tip amount during payment. If
true
, the invoice shows a tip amount field so that the customer can enter a tip amount. Iffalse
, the invoice does not show a tip amount field.Note: This feature is not available for merchants in
Hong Kong
,Taiwan
,India
, orJapan
.template_id
string
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 (contains the link_description object)
An array of request-related HATEOAS links.
invoice_item
name
string
required
The item name.
description
string
The item description.
quantity
number
required
The item quantity. Value is from
-10000
to10000
. Supports up to five decimal places.The currency and amount of the item unit price. Value is from
-1000000
to1000000
. Supports up to two decimal places.tax
The tax information.
date
string
The date when the item or service was provided, in Internet date and time format. For example, yyyy-MM-dd z.
discount
The item discount, as a percent or an amount value.
unit_of_measure
enum
The unit of measure for the invoiced item. For
AMOUNT
theunit_price
andquantity
are not shown on the invoice.Note: If your specify different
unit_of_measure
values for the same invoice, the invoice uses the first value.
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.
invoices
total_count
integer
The total number of invoices that match the search criteria.
invoices
array (contains the invoice object)
An array of invoice-level details.
Note: This array does not return item details for the invoice.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
link_description
href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the
$
,(
, and)
characters. Thehref
is the key HATEOAS component that links a completed call with a subsequent call.rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
merchant_info
email
string
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
The merchant's business name.
first_name
string
The merchant's first name.
last_name
string
The merchant's last name.
address
The merchant's address.
phone
The merchant's phone number.
fax
The merchant's fax number.
website
string
The merchant's website.
tax_id
string
The merchant's tax ID.
additional_info
string
Any additional information, such as business hours.
metadata
created_date
string
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
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
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
The date and time when the resource was first sent, in Internet date and time format.
last_sent_date
string
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
The URL for the payer's view of the invoice.
notification
subject
string
The subject of the notification. Default is a generic subject.
note
string
A note to the payer.
send_to_merchant
boolean
Indicates whether to send a copy of the email to the merchant.
cc_emails
array (contains the cc_email object)
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.
participant
email
string
required
The email address of the person who receives a copy of the invoice.
payment_detail
type
enum
The payment type in an invoicing flow. The record refund method supports the
EXTERNAL
refund type. ThePAYPAL
refund type is supported for backward compatibility.transaction_id
string
The ID for a PayPal payment transaction. Required for the
PAYPAL
payment type.transaction_type
enum
The transaction type.
date
string
The date when the invoice was paid, in Internet date and time format.
method
enum
required
The payment mode or method.
note
string
A note associated with the payment.
amount
The payment amount to record against the invoice. If you omit this parameter, the total invoice amount is marked as paid. This amount cannot exceed the amount due.
payment_term
term_type
enum
The term when the invoice payment is due.
due_date
string
The date when the invoice payment is due, in Internet date and time format. For example, yyyy-MM-dd z.
phone
country_code
string
The country code portion of the phone number, in E.164 format.
national_number
string
The in-country phone number, in E.164 format.
qr_code
image
string
The base64-encoded image of the
image/png
type.
refund_detail
type
enum
The PayPal refund type. Indicates whether the refund was paid through PayPal or externally in the invoicing flow. The record refund method supports the
EXTERNAL
refund type. ThePAYPAL
refund type is supported for backward compatibility.transaction_id
string
The ID of the PayPal refund transaction. Required for the
PAYPAL
refund type.date
string
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
The currency and amount to record as refunded. If you omit the amount, the total invoice paid amount is recorded as refunded.
search
email
string
The initial letters of the email address.
recipient_first_name
string
The initial letters of the recipient's first name.
recipient_last_name
string
The initial letters of the recipient's last name.
recipient_business_name
string
The initial letters of the recipient's business name.
number
string
Any part of the invoice number.
status
enum
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
andnotify_customer
query parameters tofalse
to suppress the PayPal email notification. Then, the merchant manually sends the invoice link in his or her own email.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
The start date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
end_invoice_date
string
The end date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
start_due_date
string
The start due date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
end_due_date
string
The end due date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
start_payment_date
string
The start payment date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
end_payment_date
string
The end payment date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
start_creation_date
string
The start creation date for the invoice, in Internet date and time format. For example, yyyy-MM-dd z.
end_creation_date
string
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
andpage_size=20
returns the first 20 invoices. A combination ofpage=20
andpage_size=20
returns the next 20 invoices.page_size
number
The page size for the search results.
total_count_required
boolean
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. Iffalse
, response lists only unarchived invoices. Ifnull
, response lists all invoices.
shipping_info
first_name
string
The first name of the recipient at the shipping address.
last_name
string
The last name of the recipient at the shipping address.
business_name
string
The business name of the recipient at the shipping address.
address
The shipping address.
summaries
summaries
array (contains the summary object)
An array of summaries of invoice data.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
summary
status
enum
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
andnotify_customer
query parameters tofalse
to suppress the PayPal email notification. Then, the merchant manually sends the invoice link in his or her own email.count
integer
The total count of invoices.
amount_summary
array (contains the amount_summary object)
An array of amounts, grouped by the currency code of the invoice.
tax
name
string
required
The tax name.
percent
number
required
The tax rate. Value is from
0
to100
. Supports up to five decimal places.amount
The currency and amount of the calculated tax.
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.
template_data
The template data.
settings
array (contains the template_settings object)
An array of template settings that describe which fields to show or hide when creating an invoice.
unit_of_measure
enum
The unit of measure for the template.
custom
boolean
Indicates whether this template is a merchant-created custom template. The system generates non-custom templates.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
template_data
The merchant business information that appears on the invoice.
billing_info
array (contains the billing_info object)
The billing information of the invoice recipient.
Note: This value is an array with only one element.
shipping_info
The shipping information for the invoice recipient.
cc_info
array (contains the email object)
An array of email addresses to which PayPal sends a copy of the invoice.
items
array (contains the invoice_item object)
An array of invoice line item information. The maximum items for an invoice is
100
.payment_term
The payment term of the invoice. If you specify
term_type
, you cannot specifydue_date
, and vice versa.reference
string
The reference data, such as a PO number.
discount
The invoice level discount, as a percent or an amount value.
shipping_cost
The shipping cost, as a percent or an amount value.
custom
The custom amount to apply to an invoice. If you include a label, you must include a custom amount.
allow_partial_payment
boolean
Indicates whether the invoice allows a partial payment. If
false
, the invoice must be paid in full. Iftrue
, the invoice allows partial payments.Note: This feature is not available for merchants in
India
,Brazil
, orIsrael
.minimum_amount_due
The currency and amount of the minimum allowed for a partial payment. Valid only when
allow_partial_payment
istrue
.tax_calculated_after_discount
boolean
Indicates whether the tax is calculated before or after a discount. If
false
, the tax is calculated before a discount. Iftrue
, the tax is calculated after a discount.tax_inclusive
boolean
Indicates whether the unit price includes tax.
terms
string
The general terms of the invoice.
note
string
A note to the invoice recipient. This note also appears on the invoice notification email.
merchant_memo
string
A private bookkeeping memo for the merchant.
logo_url
string
The full URL to an external logo image. The logo image must not be larger than 250 pixels wide by 90 pixels high.
total_amount
The currency and amount of the invoice total.
attachments
array (contains the file_attachment object)
An array of PayPal file IDs for the files that are attached to an invoice. The maximum number of files is
5
.
template_settings
field_name
enum
The field name in
template_data
for which to map corresponding display preferences.display_preference
The template settings metadata.
template_settings_metadata
hidden
boolean
Indicates whether to show or hide this field.
templates
addresses
array (contains the address object)
An array of postal addresses in the user's PayPal profile.
emails
array (contains the email object)
An array of email addresses in the user's PayPal profile.
phones
array (contains the phone object)
An array of phone numbers in the user's PayPal profile.
templates
array (contains the template object)
The details for each template. If
fields
isnone
, returns only the template name, ID, and default status.links
array (contains the link_description object)
An array of request-related HATEOAS links.
Additional API information
Error messages
In addition to the common HTTP status codes that the REST APIs return, the Invoicing API can return the following errors.