Invoicing (1)

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

Create draft invoice

post/v1/invoicing/invoices
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Creates a draft invoice. To move the invoice from a draft to payable state, you must send the invoice.

In the JSON request body, include invoice details including merchant information. The invoice object must include an items array.
Note: The merchant that you specify in an invoice must have a PayPal account in good standing.
.
SecurityOauth2
Request
Request Body schema:
number
string <= 25 characters

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

Array of objects (billing_info) = 1 items

An array of billing information for the invoice recipient.

Note: This value is an array with only one element.

Array of objects (Participant)

An array of email addresses to which PayPal sends a copy of the invoice.

Array of objects (invoice_item) <= 100 items

An array of invoice line item information.

invoice_date
string <date>

The invoice date as specified by the sender, in Internet date and time format.

reference
string <= 60 characters

The reference data, such as PO number.

allow_partial_payment
boolean
Default: false

Indicates whether the invoice allows a partial payment. If false, the invoice must be paid in full. If true, the invoice allows partial payments.

Note: This feature is not available for merchants in India, Brazil, or Israel.

tax_calculated_after_discount
boolean
Default: false

Indicates whether the tax is calculated before or after a discount. If false, the tax is calculated before a discount. If true, the tax is calculated after a discount.

tax_inclusive
boolean
Default: false

Indicates whether the unit price includes tax.

terms
string <= 4000 characters

The general terms of the invoice.

note
string <= 4000 characters

A note to the invoice recipient. The note also appears on the invoice notification email.

merchant_memo
string <= 500 characters

A private bookkeeping memo for the merchant.

logo_url
string <uri> <= 4000 characters

The full URL to an external logo image. The logo must not be larger than 250 pixels wide by 90 pixels high. The logo must be stored on a secure server.

allow_tip
boolean
Default: false

Indicates whether the invoice enables the customer to enter a tip amount during payment. If true, the invoice shows a tip amount field so that the customer can enter a tip amount. If false, the invoice does not show a tip amount field.

Note: This feature is not available for merchants in Hong Kong, Taiwan, India, or Japan.

template_id
string
Default: "PayPal system template"

This value is only used to determine the layout to display on the create or edit invoice experience, such as which fields to show and hide. It does not impact the view of the invoice that the customer receives.

Note: If you are just using the Invoicing APIs to create and send invoices, leave this field blank. The template_id is only needed if you use the Invoicing API to build a full invoicing solution that includes templates.

required
object (merchant_info)

The merchant business information that appears on the invoice.

object (shipping_info)

The shipping information for the invoice recipient.

object (payment_term)

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

object (Discount)

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

object (shipping_cost)

The shipping cost, as a percent or amount value.

object (custom_amount)

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

object (Currency)

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

Responses
201

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

Request samples
{
  • "merchant_info": {
    • "email": "merchant@example.com",
    • "first_name": "David",
    • "last_name": "Larusso",
    • "business_name": "Mitchell & Murray",
    • "phone": {
      • "country_code": "001",
      • "national_number": "4085551234"
      },
    • "address": {
      • "line1": "1234 First Street",
      • "city": "Anytown",
      • "state": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      }
    },
  • "billing_info": [
    • {
      • "email": "bill-me@example.com",
      • "first_name": "Stephanie",
      • "last_name": "Meyers"
      }
    ],
  • "shipping_info": {
    • "first_name": "Stephanie",
    • "last_name": "Meyers",
    • "address": {
      • "line1": "1234 Main Street",
      • "city": "Anytown",
      • "state": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      }
    },
  • "items": [
    • {
      • "name": "Zoom System wireless headphones",
      • "quantity": 2,
      • "unit_price": {
        • "currency": "USD",
        • "value": "120"
        },
      • "tax": {
        • "name": "Tax",
        • "percent": 8
        }
      },
    • {
      • "name": "Bluetooth speaker",
      • "quantity": 1,
      • "unit_price": {
        • "currency": "USD",
        • "value": "145"
        },
      • "tax": {
        • "name": "Tax",
        • "percent": 8
        }
      }
    ],
  • "discount": {
    • "percent": 1
    },
  • "shipping_cost": {
    • "amount": {
      • "currency": "USD",
      • "value": "10"
      }
    },
  • "note": "Thank you for your business.",
  • "terms": "No refunds after 30 days."
}
Response samples
application/json
{
  • "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": []
}

List invoices

get/v1/invoicing/invoices
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Lists invoices. To filter the invoices that appear in the response, you can specify one or more optional query parameters.
SecurityOauth2
Request
query Parameters
page
integer
Default: 1

The zero-relative start index of the entire list of merchant invoices that are returned in the response. So, the combination of page=0 and page_size=20 returns the first 20 invoices. The combination of page=20 and page_size=20 returns the next 20 invoices.

page_size
integer
Default: 20

The number of invoices to return in the response.

total_count_required
boolean
Default: false

Indicates whether to show the total count in the response.

Request Body schema:
any
Responses
200

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

Request samples
{ }
Response samples
application/json
{
  • "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": []
}

Send invoice

post/v1/invoicing/invoices/{invoice_id}/send
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Sends an invoice, by ID, to a customer. To suppress the merchant's email notification, set the `notify_merchant` query parameter to `false`.
Note: After you send an invoice, you cannot resend it.
SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice to send.

query Parameters
notify_merchant
boolean
Default: true

Indicates whether to send the invoice update notification to the merchant.

Request Body schema:
any
Responses
202

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

Request samples
{ }
Response samples
application/json
{ }

Schedule invoice

post/v1/invoicing/invoices/{invoice_id}/schedule
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Schedules an invoice, by ID, to send on a future date. At 07:00 on that date in the preferred time zone of the merchant's PayPal account profile, PayPal emails an invoice notification to the merchant and the customer, adds an online payment button to the customer’s view of the invoice, and updates the invoice status to SENT.
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.
SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice to schedule.

Request Body schema:
any
Responses
202

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

Request samples
{ }
Response samples
application/json
{}

Send invoice reminder

post/v1/invoicing/invoices/{invoice_id}/remind
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Sends a reminder to the payer about an invoice, by ID. In the JSON request body, include a `notification` object that defines the subject of the reminder and other details.
SecurityOauth2
Request
path Parameters
invoice_id
required
string

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

Request Body schema:
subject
string

The subject of the notification. Default is a generic subject.

note
string

A note to the payer.

send_to_merchant
boolean
Default: true

Indicates whether to send a copy of the email to the merchant.

cc_emails
Array of strings <= 100 items

An array of one or more CC: emails to which to send notification emails. If you omit this parameter, the API sends notification emails to all CC: email addresses that are part of the invoice.

Note: Valid values are email addresses in the cc_info array of the invoice.

Responses
202

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

Request samples
{
  • "subject": "Past due",
  • "note": "Please pay soon",
  • "send_to_merchant": true,
  • "cc_emails": [
    • "cc-email@example.com"
    ]
}
Response samples
application/json
{ }

Cancel sent invoice

post/v1/invoicing/invoices/{invoice_id}/cancel
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Cancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and CC: emails.
SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice to cancel.

Request Body schema:
subject
string

The subject of the notification. If left blank we include a generic subject.

note
string

A note to the payer.

send_to_merchant
boolean
Default: true

Indicates whether to send the notification to the merchant.

send_to_payer
boolean
Default: true

Indicates whether to send the notification to the payer.

cc_emails
Array of strings <= 100 items

An array of one or more CC: emails to which to send notification emails. If you omit this parameter, the API sends notification emails to all CC: email addresses that are part of the invoice.

Note: Additional email addresses are not supported.

Responses
204

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

Request samples
{
  • "subject": "Invoice canceled",
  • "note": "Canceling this invoice per your request.",
  • "send_to_merchant": true,
  • "send_to_payer": true,
  • "cc_emails": [
    • "cc-email@example.com"
    ]
}
Response samples
application/json
{ }

Mark invoice as paid

post/v1/invoicing/invoices/{invoice_id}/record-payment
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Marks the status of an invoice, by ID, as paid.
SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice to mark as paid.

Request Body schema:
date
string <date-time>

The date when the invoice was paid, in Internet date and time format.

method
required
string

The payment mode or method.

Enum: "BANK_TRANSFER" "CASH" "CHECK" "CREDIT_CARD" "DEBIT_CARD" "PAYPAL" "WIRE_TRANSFER" "OTHER"
note
string

A note associated with the payment.

object (Currency)

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

Responses
200

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

Request samples
{
  • "method": "CASH",
  • "date": "2013-11-06 03:30:00 PST",
  • "note": "I got the payment by cash!",
  • "amount": {
    • "currency": "USD",
    • "value": "20.00"
    }
}
Response samples
application/json
{ }

Mark invoice as refunded

post/v1/invoicing/invoices/{invoice_id}/record-refund
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Marks the status of an invoice, by ID, as refunded.
SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice to mark as refunded.

Request Body schema:
date
string <date-time>

The date when the invoice was refunded, in Internet date and time format. For example, 2014-02-27 PST.

note
string

A note associated with the refund.

object (Currency)

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

Responses
200

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

Request samples
{
  • "date": "2013-11-10 14:00:00 PST",
  • "note": "Refunded by cash!",
  • "amount": {
    • "currency": "USD",
    • "value": "20.00"
    }
}
Response samples
application/json
{ }

Show invoice details

get/v1/invoicing/invoices/{invoice_id}
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Shows details for an invoice, by ID.
SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice for which to show details.

Responses
200

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

Request samples 
Response samples 
application/json
{
  • "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": []
}
Update invoice
put/v1/invoicing/invoices/{invoice_id}
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Fully updates an invoice, by ID. In the JSON request body, include a complete `invoice` object. This call does not support partial updates.
SecurityOauth2 
Request 
path Parameters
invoice_id
required
string
The ID of the invoice to update.


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


 
Request Body schema: application/json
number
string  <= 25 characters 
The invoice number. If you omit this value, the default is the number that the API automatically increments from the last number.


 
Array of objects (billing_info)   = 1 items 
An array of billing information for the invoice recipient.
Note: This value is an array with only one element.


 
Array of objects (Participant) 
An array of email addresses to which PayPal sends a copy of the invoice.


 
Array of objects (invoice_item)   <= 100 items 
An array of invoice line item information.


 
invoice_date
string <date> 
The invoice date as specified by the sender, in Internet date and time format.


 
reference
string  <= 60 characters 
The reference data, such as PO number.


 
allow_partial_payment
boolean
 Default:  false
Indicates whether the invoice allows a partial payment. If false, the invoice must be paid in full. If true, the invoice allows partial payments.
Note: This feature is not available for merchants in India, Brazil, or Israel.


 
tax_calculated_after_discount
boolean
 Default:  false
Indicates whether the tax is calculated before or after a discount. If false, the tax is calculated before a discount. If true, the tax is calculated after a discount.


 
tax_inclusive
boolean
 Default:  false
Indicates whether the unit price includes tax.


 
terms
string  <= 4000 characters 
The general terms of the invoice.


 
note
string  <= 4000 characters 
A note to the invoice recipient. The note also appears on the invoice notification email.


 
merchant_memo
string  <= 500 characters 
A private bookkeeping memo for the merchant.


 
logo_url
string <uri>   <= 4000 characters 
The full URL to an external logo image. The logo must not be larger than 250 pixels wide by 90 pixels high. The logo must be stored on a secure server.


 
allow_tip
boolean
 Default:  false
Indicates whether the invoice enables the customer to enter a tip amount during payment. If true, the invoice shows a tip amount field so that the customer can enter a tip amount. If false, the invoice does not show a tip amount field.
Note: This feature is not available for merchants in Hong Kong, Taiwan, India, or Japan.


 
template_id
string
 Default:  "PayPal system template"
This value is only used to determine the layout to display on the create or edit invoice experience, such as which fields to show and hide. It does not impact the view of the invoice that the customer receives.
Note: If you are just using the Invoicing APIs to create and send invoices, leave this field blank. The template_id is only needed if you use the Invoicing API to build a full invoicing solution that includes templates.


 
required
object (merchant_info) 
The merchant business information that appears on the invoice.


 
object (shipping_info) 
The shipping information for the invoice recipient.


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


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


 
object (shipping_cost) 
The shipping cost, as a percent or amount value.


 
object (custom_amount) 
The custom amount to apply to an invoice. If you include a label, you must include a custom amount.


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


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


Request samples 
application/json
{
  • "merchant_info": {
    • "email": "merchant@example.com",
    • "first_name": "Dennis",
    • "last_name": "Doctor",
    • "business_name": "Medical Professionals, LLC",
    • "phone": {
      • "country_code": "001",
      • "national_number": "5032141716"
      },
    • "address": {
      • "line1": "1234 Main St.",
      • "city": "Portland",
      • "state": "OR",
      • "postal_code": "97217",
      • "country_code": "US"
      }
    },
  • "billing_info": [
    • {
      • "email": "bill-me@example.com"
      }
    ],
  • "items": [
    • {
      • "name": "Sutures",
      • "quantity": 100,
      • "unit_price": {
        • "currency": "USD",
        • "value": "5"
        }
      }
    ],
  • "note": "Medical Invoice 16 Jul, 2013 PST",
  • "payment_term": {
    • "term_type": "NET_45"
    },
  • "shipping_info": {
    • "first_name": "Sally",
    • "last_name": "Patient",
    • "business_name": "Not applicable",
    • "address": {
      • "line1": "1234 Broad St.",
      • "city": "Portland",
      • "state": "OR",
      • "postal_code": "97216",
      • "country_code": "US"
      }
    }
}
Response samples 
application/json
{
  • "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"
    }
}
Delete draft invoice
delete/v1/invoicing/invoices/{invoice_id}
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Deletes invoices in the DRAFT or SCHEDULED state, by ID. For invoices that have already been sent, you can cancel the invoice. After you delete a draft or scheduled invoice, you can no longer use it or show its details. However, you can reuse its invoice number.
SecurityOauth2 
Request 
path Parameters
invoice_id
required
string
The ID of the draft invoice to delete.


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


Request samples 
Response samples 
application/json
{ }
Delete external payment
delete/v1/invoicing/invoices/{invoice_id}/payment-records/{transaction_id}
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Deletes an external payment, by invoice ID and transaction ID.
SecurityOauth2 
Request 
path Parameters
invoice_id
required
string
The ID of the invoice from which to delete an external payment transaction.


 
transaction_id
required
string
The ID of the external payment transaction to delete.


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


Request samples 
Response samples 
application/json
{ }
Delete external refund
delete/v1/invoicing/invoices/{invoice_id}/refund-records/{transaction_id}
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Deletes an external refund, by invoice ID and transaction ID.
SecurityOauth2 
Request 
path Parameters
invoice_id
required
string
The ID of the invoice from which to delete the external refund transaction.


 
transaction_id
required
string
The ID of the external refund transaction to delete.


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


Request samples 
Response samples 
application/json
{ }
Generate QR code
get/v1/invoicing/invoices/{invoice_id}/qr-code
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Generates a QR code for an invoice, by ID. The QR code is a PNG image in Base64-encoded format that corresponds to the invoice ID. You can generate a QR code for an invoice and add it to a paper or PDF invoice. When customers use their mobile devices to scan the QR code, they are redirected to the PayPal mobile payment flow where they can view the invoice and pay online with PayPal or a credit card. Before you get a QR code, you must create an invoice and send an invoice to move the invoice from a draft to payable state. Do not include an email address if you do not want the invoice emailed.
SecurityOauth2 
Request 
path Parameters
invoice_id
required
string
The ID of the invoice for which to generate a QR code.


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


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


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


Request samples 
Response samples 
application/json
{
  • "image": "iVBORw0KGgoAA......XUDM"
}
Generate invoice number
post/v1/invoicing/invoices/next-invoice-number
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Generates the next invoice number that is available to the merchant. The next invoice number uses the prefix and suffix from the last invoice number and increments the number by one. For example, the next invoice number after `INVOICE-1234` is `INVOICE-1235`.
SecurityOauth2 
Request 
Request Body schema: 
any
 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that shows the next invoice number.


Request samples 
{ }
Response samples 
application/json
{
  • "number": "ee0044"
}
Create template
post/v1/invoicing/templates
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Creates an invoice template. You can use details from this template to create an invoice. You can create up to 50 templates.
Note: Every merchant starts with three PayPal system templates that are optimized for the unit type billed. The template includes `Quantity`, `Hours`, and `Amount`.
SecurityOauth2 
Request 
Request Body schema: 
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.


 
Array of objects (template_settings) 
An array of template settings that describe which fields to show or hide when creating an invoice.


 
unit_of_measure
string
The unit of measure for the template.


 Enum: "HOURS" "QUANTITY" "AMOUNT"  
object (template_data) 
The template data.


 
Responses 
201
Created


Request samples 
{
  • "name": "Hours Template",
  • "default": true,
  • "unit_of_measure": "HOURS",
  • "template_data": {
    • "merchant_info": {
      • "email": "doctor@example.com",
      • "first_name": "Dennis",
      • "last_name": "Doctor",
      • "business_name": "Medical Professionals, LLC",
      • "phone": {
        • "country_code": "001",
        • "national_number": "5032141716"
        },
      • "address": {
        • "line1": "1234 Main St.",
        • "city": "Portland",
        • "state": "OR",
        • "postal_code": "97217",
        • "country_code": "US"
        }
      },
    • "items": [
      • {
        • "name": "Nutri Bullet",
        • "quantity": 1,
        • "unit_price": {
          • "currency": "USD",
          • "value": "50.00"
          }
        }
      ],
    • "tax_calculated_after_discount": false,
    • "tax_inclusive": false,
    • "note": "Thank you for your business.",
    • "logo_url": "https://example.com/v1/images/redDot.jpeg"
    },
  • "settings": [
    • {
      • "field_name": "items.date",
      • "display_preference": {
        • "hidden": true
        }
      },
    • {
      • "field_name": "custom",
      • "display_preference": {
        • "hidden": true
        }
      }
    ]
}
Response samples 
application/json
{
  • "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": []
}
List templates
get/v1/invoicing/templates
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Lists merchant-created templates with associated details. The associated details include the email addresses, postal addresses, and phone numbers from the user's PayPal profile.
The user can select which values to show in the business information section of their template.
SecurityOauth2 
Request 
query Parameters
fields
string
 Default:  "all"
The fields to return in the response. Value is all or none. To return only the template name, ID, and default attributes, specify none.


 
Request Body schema: 
any
 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that lists invoices.


Request samples 
{ }
Response samples 
application/json
{
  • "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": []
      }
    ],
  • "links": []
}
Show template details
get/v1/invoicing/templates/{template_id}
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Shows details for a template, by ID.
SecurityOauth2 
Request 
path Parameters
template_id
required
string
The ID of the template for which to show details.


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


Request samples 
Response samples 
application/json
{
  • "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": []
}
Delete template
delete/v1/invoicing/templates/{template_id}
Deletes a template, by ID.


SecurityOauth2 
Request 
path Parameters
template_id
required
string
The ID of the template to delete.


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


Request samples 
Response samples 
application/json
{ }
Update template
put/v1/invoicing/templates/{template_id}
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Updates a template, by ID. In the JSON request body, specify a complete `template` object. The update method does not support partial updates.
SecurityOauth2 
Request 
path Parameters
template_id
required
string
The ID of the template to update.


 
Request Body schema: application/json
name
string
The template name.
Note: The template name must be unique.


 
default
boolean
Indicates whether this template is the default merchant template. A merchant can have one default template.


 
Array of objects (template_settings) 
An array of template settings that describe which fields to show or hide when creating an invoice.


 
unit_of_measure
string
The unit of measure for the template.


 Enum: "HOURS" "QUANTITY" "AMOUNT"  
object (template_data) 
The template data.


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


Request samples 
application/json
{
  • "template_id": "TEMP-XYZ",
  • "name": "Hours Template",
  • "default": true,
  • "unit_of_measure": "HOURS",
  • "template_data": {
    • "merchant_info": {
      • "email": "doctor@example.com",
      • "first_name": "Dennis",
      • "last_name": "Doctor",
      • "business_name": "Medical Professionals, LLC",
      • "phone": {
        • "country_code": "001",
        • "national_number": "5032141716"
        },
      • "address": {
        • "line1": "1234 Main St.",
        • "city": "Portland",
        • "state": "OR",
        • "postal_code": "97217",
        • "country_code": "US"
        }
      },
    • "items": [
      • {
        • "name": "Nutri Bullet",
        • "quantity": 1,
        • "unit_price": {
          • "currency": "USD",
          • "value": "50.00"
          }
        }
      ],
    • "tax_calculated_after_discount": false,
    • "tax_inclusive": false,
    • "note": "Thank you for your business.",
    • "logo_url": "https://example.com/v1/images/redDot.jpeg"
    },
  • "settings": [
    • {
      • "field_name": "items.date",
      • "display_preference": {
        • "hidden": true
        }
      },
    • {
      • "field_name": "custom",
      • "display_preference": {
        • "hidden": true
        }
      }
    ]
}
Response samples 
application/json
{
  • "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": []
}
Errors
AUTHORIZATION_ERROR
Message:
Authorization error occurred.


Description: Check your credentials.




BUSINESS_ERROR
Message:
Invoicing business error.


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




INTERNAL_SERVICE_ERROR
Message:
An internal service error has occurred.


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




MALFORMED_REQUEST_ERROR
Message:
JSON request malformed.


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




RESOURCE_NOT_FOUND_ERROR
Message:
Resource not found.


Description: The resource was not found.




UNKNOWN_ERROR
Message:
Unknown exception occurred.


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




USER_BUSINESS_ERROR
Message:
User business error.


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




VALIDATION_ERROR
Message:
Invalid request - see details.


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


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


line1
required
string
The first line of the address. For example, number or street.


 
line2
string
The second line of the address. For example, suite or apartment number.


 
city
required
string
The city name.


 
country_code
required
string
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.


 
postal_code
string
The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.


 
state
string
The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, China, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.


 
phone
string <phone> 
The phone number, in its canonical international E.164 numbering plan format.


 
{
  • "line1": "string",
  • "line2": "string",
  • "city": "string",
  • "country_code": "string",
  • "postal_code": "string",
  • "state": "string",
  • "phone": "string"
}
amount_summary
The summary of the invoice total and paid and refunded amounts, grouped by currency code.


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


 
object (payment_summary) 
The payment and refund summary.


 
object (payment_summary) 
The payment and refund summary.


 
{
  • "total_amount": {
    • "currency": "string",
    • "value": "string"
    },
  • "paid_amount": {
    • "paypal": {
      • "currency": "string",
      • "value": "string"
      },
    • "other": {
      • "currency": "string",
      • "value": "string"
      }
    },
  • "refunded_amount": {
    • "paypal": {
      • "currency": "string",
      • "value": "string"
      },
    • "other": {
      • "currency": "string",
      • "value": "string"
      }
    }
}
billing_info
The billing information for the invoice recipient.


email
string <email>   <= 260 characters 
The invoice recipient email address. If you omit this value, the invoice is payable and a notification email is not sent.


 
first_name
string  <= 30 characters 
The invoice recipient's first name.


 
last_name
string  <= 30 characters 
The invoice recipient's last name.


 
business_name
string  <= 100 characters 
The invoice recipient's business name.


 
language
string
The language in which the invoice recipient's email appears. Used only when the recipient does not have a PayPal account.
If you omit the language and the recipient does not have a PayPal account, the email is sent in the language of the merchant's PayPal account.


 Enum: "da_DK" "de_DE" "en_AU" "en_GB" "en_US" "es_ES" "es_XC" "fr_CA" "fr_FR" "fr_XC" "he_IL" "id_ID" "it_IT" "ja_JP" "nl_NL" "no_NO" "pl_PL" "pt_BR" "pt_PT" "ru_RU" "sv_SE" "th_TH" "tr_TR" "zh_CN" "zh_HK" "zh_TW" "zh_XC"  
additional_info
string  <= 40 characters 
Any additional information about the recipient.


 
object (Phone) 
The phone number.


 
object (Address) 
The address, which is either a billing address or shipping address in a payment.


 
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "business_name": "string",
  • "language": "da_DK",
  • "additional_info": "string",
  • "phone": {
    • "country_code": "str",
    • "national_number": "string"
    },
  • "address": {
    • "line1": "string",
    • "line2": "string",
    • "city": "string",
    • "country_code": "string",
    • "postal_code": "string",
    • "state": "string",
    • "phone": "string"
    }
}
cancel_notification
Cancels an email or SMS notification.


subject
string
The subject of the notification. If left blank we include a generic subject.


 
note
string
A note to the payer.


 
send_to_merchant
boolean
 Default:  true
Indicates whether to send the notification to the merchant.


 
send_to_payer
boolean
 Default:  true
Indicates whether to send the notification to the payer.


 
cc_emails
Array of strings  <= 100 items 
An array of one or more CC: emails to which to send notification emails. If you omit this parameter, the API sends notification emails to all CC: email addresses that are part of the invoice.
Note: Additional email addresses are not supported.


 
{
  • "subject": "string",
  • "note": "string",
  • "send_to_merchant": true,
  • "send_to_payer": true,
  • "cc_emails": [
    • "string"
    ]
}
Currency
The currency and amount for a financial transaction, such as a balance or payment due.


currency
required
value
required
string
The value, which might be:
  • An integer for currencies like JPY that are not typically fractional.
  • A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency codes - ISO 4217.


 
{
  • "currency": "string",
  • "value": "string"
}
custom_amount
The custom amount to apply to an invoice. If you include a label, you must include a custom amount.


label
string  <= 50 characters 
The custom amount label.


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


 
{
  • "label": "string",
  • "amount": {
    • "currency": "string",
    • "value": "string"
    }
}
Discount
The discount as a percent or an amount value. For example, to specify 10%, enter 10. Alternatively, to specify an amount of 5, enter 5.


percent
number
The discount as a percentage value. Value is from 0 to 100. Supports up to five decimal places.


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


 
{
  • "percent": 0,
  • "amount": {
    • "currency": "string",
    • "value": "string"
    }
}
Email
The participant's email address.


string <email>  (Email) 
The participant's email address.


 
"user@example.com"
Error
The error information.


name
required
string
The human-readable, unique name of the error.


 
debug_id
string
The PayPal internal ID. Used for correlation purposes.


 
message
required
string
The message that describes the error.


 
information_link
required
string
The URI to detailed information related to this error for the developer.


 
Array of objects (Error Details) 
An array of additional details for the error.


 
{
  • "name": "string",
  • "debug_id": "string",
  • "message": "string",
  • "information_link": "string",
  • "details": [
    • {
      • "field": "string",
      • "issue": "string"
      }
    ]
}
Error Details
The error details. Required for client-side 4XX errors.


field
required
string
The name of the field that caused the error.


 
issue
required
string
The reason for the error.


 
{
  • "field": "string",
  • "issue": "string"
}
file_attachment
The file that is attached to an invoice or template.


name
string
The name of the attached file.


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


 
{}
Invoice
The invoice details.


id
string
The ID of the invoice.


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


 
status
string
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: 
StatusOccurs when
DRAFT
A merchant creates a draft invoice.
Note: A customer cannot pay an invoice with this status. A customer cannot pay an invoice until it has a status of SENT or UNPAID.
UNPAID
A merchant chooses to suppress the PayPal email notification when he or she sends the invoice through the API or the Create Invoice page, and then manually sends the invoice link in his or her own email.
To send an invoice without email notification, the merchant either:
  • Sets the notify_merchant and notify_customer query parameters to false when he or she sends the invoice.
  • Selects Share link myself from the Send menu when he or she sends the invoice through the web UI Create Invoice page.
SENT
A merchant accepts the default PayPal email notification when he or she sends the invoice through the API or the Create Invoice page. PayPal automatically emails the invoice to the customer and a Pay button appears on the invoice, which enables the customer to pay the invoice. In a web app, the invoice appears as Unpaid (sent).
SCHEDULED
A merchant schedules an invoice to send on a future date. At 07:00 on that date in the preferred time zone of the merchant's PayPal account profile, PayPal emails an invoice notification to the merchant and the customer, adds an online payment button to the customer’s view of the invoice, and updates the invoice status to SENT.
PARTIALLY_PAID
A customer makes a partial payment for the invoice through one of these methods:
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:
MARKED_AS_PAID
A customer makes a disconnected payment for the balance of the invoice. The merchant manually marks the invoice as paid.
CANCELLED
A merchant or customer cancels a sent invoice. You can cancel an invoice in SENT or UNPAID status.
REFUNDED
A merchant fully refunds an invoice through one these methods:
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.


 Enum: "DRAFT" "UNPAID" "SENT" "SCHEDULED" "PARTIALLY_PAID" "PAYMENT_PENDING" "PAID" "MARKED_AS_PAID" "CANCELLED" "REFUNDED" "PARTIALLY_REFUNDED" "MARKED_AS_REFUNDED"  
Array of objects (billing_info)   = 1 items 
An array of billing information for the invoice recipient.
Note: This value is an array with only one element.


 
Array of objects (Participant) 
An array of email addresses to which PayPal sends a copy of the invoice.


 
Array of objects (invoice_item)   <= 100 items 
An array of invoice line item information.


 
invoice_date
string <date> 
The invoice date as specified by the sender, in Internet date and time format.


 
reference
string  <= 60 characters 
The reference data, such as PO number.


 
allow_partial_payment
boolean
 Default:  false
Indicates whether the invoice allows a partial payment. If false, the invoice must be paid in full. If true, the invoice allows partial payments.
Note: This feature is not available for merchants in India, Brazil, or Israel.


 
tax_calculated_after_discount
boolean
 Default:  false
Indicates whether the tax is calculated before or after a discount. If false, the tax is calculated before a discount. If true, the tax is calculated after a discount.


 
tax_inclusive
boolean
 Default:  false
Indicates whether the unit price includes tax.


 
terms
string  <= 4000 characters 
The general terms of the invoice.


 
note
string  <= 4000 characters 
A note to the invoice recipient. The note also appears on the invoice notification email.


 
merchant_memo
string  <= 500 characters 
A private bookkeeping memo for the merchant.


 
logo_url
string <uri>   <= 4000 characters 
The full URL to an external logo image. The logo must not be larger than 250 pixels wide by 90 pixels high. The logo must be stored on a secure server.


 
Array of objects (payment_detail)   <= 1 items 
An array of payment details for the invoice.


 
Array of objects (refund_detail)   <= 1 items 
An array of refund details for the invoice.


 
Array of objects (file_attachment) 
An array of PayPal file IDs for the files that are attached to an invoice. You can attach up to five files.


 
allow_tip
boolean
 Default:  false
Indicates whether the invoice enables the customer to enter a tip amount during payment. If true, the invoice shows a tip amount field so that the customer can enter a tip amount. If false, the invoice does not show a tip amount field.
Note: This feature is not available for merchants in Hong Kong, Taiwan, India, or Japan.


 
template_id
string
 Default:  "PayPal system template"
This value is only used to determine the layout to display on the create or edit invoice experience, such as which fields to show and hide. It does not impact the view of the invoice that the customer receives.
Note: If you are just using the Invoicing APIs to create and send invoices, leave this field blank. The template_id is only needed if you use the Invoicing API to build a full invoicing solution that includes templates.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
required
object (merchant_info) 
The merchant business information that appears on the invoice.


 
object (shipping_info) 
The shipping information for the invoice recipient.


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


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


 
object (shipping_cost) 
The shipping cost, as a percent or amount value.


 
object (custom_amount) 
The custom amount to apply to an invoice. If you include a label, you must include a custom amount.


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


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


 
object (Metadata) 
The audit metadata.


 
object (payment_summary) 
The payment and refund summary.


 
object (payment_summary) 
The payment and refund summary.


 
{
  • "id": "string",
  • "number": "string",
  • "status": "DRAFT",
  • "billing_info": [
    • {
      • "email": "user@example.com",
      • "first_name": "string",
      • "last_name": "string",
      • "business_name": "string",
      • "language": "da_DK",
      • "additional_info": "string",
      • "phone": {
        • "country_code": "str",
        • "national_number": "string"
        },
      • "address": {
        • "line1": "string",
        • "line2": "string",
        • "city": "string",
        • "country_code": "string",
        • "postal_code": "string",
        • "state": "string",
        • "phone": "string"
        }
      }
    ],
  • "cc_info": [
    • {
      • "email": "user@example.com"
      }
    ],
  • "items": [
    • {
      • "name": "string",
      • "description": "string",
      • "quantity": 0,
      • "date": "2019-08-24",
      • "unit_of_measure": "QUANTITY",
      • "unit_price": {
        • "currency": "string",
        • "value": "string"
        },
      • "tax": {
        • "name": "string",
        • "percent": 0,
        • "amount": {
          • "currency": "string",
          • "value": "string"
          }
        },
      • "discount": {
        • "percent": 0,
        • "amount": {
          • "currency": "string",
          • "value": "string"
          }
        }
      }
    ],
  • "invoice_date": "2019-08-24",
  • "reference": "string",
  • "allow_partial_payment": false,
  • "tax_calculated_after_discount": false,
  • "tax_inclusive": false,
  • "terms": "string",
  • "note": "string",
  • "merchant_memo": "string",
  • "logo_url": "http://example.com",
  • "payments": [
    • {
      • "type": "PAYPAL",
      • "transaction_id": "string",
      • "transaction_type": "SALE",
      • "date": "2019-08-24T14:15:22Z",
      • "method": "BANK_TRANSFER",
      • "note": "string",
      • "amount": {
        • "currency": "string",
        • "value": "string"
        }
      }
    ],
  • "refunds": [
    • {
      • "type": "PAYPAL",
      • "transaction_id": "string",
      • "date": "2019-08-24T14:15:22Z",
      • "note": "string",
      • "amount": {
        • "currency": "string",
        • "value": "string"
        }
      }
    ],
  • "attachments": [],
  • "allow_tip": false,
  • "template_id": "PayPal system template",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "merchant_info": {
    • "email": "user@example.com",
    • "business_name": "string",
    • "first_name": "string",
    • "last_name": "string",
    • "website": "http://example.com",
    • "tax_id": "string",
    • "additional_info": "string",
    • "address": {
      • "line1": "string",
      • "line2": "string",
      • "city": "string",
      • "country_code": "string",
      • "postal_code": "string",
      • "state": "string",
      • "phone": "string"
      },
    • "phone": {
      • "country_code": "str",
      • "national_number": "string"
      },
    • "fax": {
      • "country_code": "str",
      • "national_number": "string"
      }
    },
  • "shipping_info": {
    • "first_name": "string",
    • "last_name": "string",
    • "business_name": "string",
    • "address": {
      • "line1": "string",
      • "line2": "string",
      • "city": "string",
      • "country_code": "string",
      • "postal_code": "string",
      • "state": "string",
      • "phone": "string"
      }
    },
  • "payment_term": {
    • "term_type": "DUE_ON_RECEIPT",
    • "due_date": "2019-08-24"
    },
  • "discount": {
    • "percent": 0,
    • "amount": {
      • "currency": "string",
      • "value": "string"
      }
    },
  • "shipping_cost": {
    • "amount": {
      • "currency": "string",
      • "value": "string"
      },
    • "tax": {
      • "name": "string",
      • "percent": 0,
      • "amount": {
        • "currency": "string",
        • "value": "string"
        }
      }
    },
  • "custom": {
    • "label": "string",
    • "amount": {
      • "currency": "string",
      • "value": "string"
      }
    },
  • "minimum_amount_due": {
    • "currency": "string",
    • "value": "string"
    },
  • "total_amount": {
    • "currency": "string",
    • "value": "string"
    },
  • "metadata": {
    • "created_date": "2019-08-24T14:15:22Z",
    • "created_by": "string",
    • "cancelled_date": "2019-08-24T14:15:22Z",
    • "cancelled_by": "string",
    • "last_updated_date": "2019-08-24T14:15:22Z",
    • "last_updated_by": "string",
    • "first_sent_date": "2019-08-24T14:15:22Z",
    • "last_sent_date": "2019-08-24T14:15:22Z",
    • "last_sent_by": "string",
    • "payer_view_url": "http://example.com"
    },
  • "paid_amount": {
    • "paypal": {
      • "currency": "string",
      • "value": "string"
      },
    • "other": {
      • "currency": "string",
      • "value": "string"
      }
    },
  • "refunded_amount": {
    • "paypal": {
      • "currency": "string",
      • "value": "string"
      },
    • "other": {
      • "currency": "string",
      • "value": "string"
      }
    }
}
Invoice Number
The invoice number.


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


 
{
  • "number": "string"
}
invoice_item
The invoice line item information.


name
required
string  <= 200 characters 
The item name.


 
description
string  <= 1000 characters 
The item description.


 
quantity
required
number
The item quantity. Value is from -10000 to 10000. Supports up to five decimal places.


 
date
string <date> 
The date when the item or service was provided, in Internet date and time format. For example, yyyy-MM-dd z.


 
unit_of_measure
string
The unit of measure for the invoiced item. For AMOUNT the unit_price and quantity are not shown on the invoice.
Note: If your specify different unit_of_measure values for the same invoice, the invoice uses the first value.


 Enum: "QUANTITY" "HOURS" "AMOUNT"  
required
object (Currency) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
object (Tax) 
The tax information.


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


 
{
  • "name": "string",
  • "description": "string",
  • "quantity": 0,
  • "date": "2019-08-24",
  • "unit_of_measure": "QUANTITY",
  • "unit_price": {
    • "currency": "string",
    • "value": "string"
    },
  • "tax": {
    • "name": "string",
    • "percent": 0,
    • "amount": {
      • "currency": "string",
      • "value": "string"
      }
    },
  • "discount": {
    • "percent": 0,
    • "amount": {
      • "currency": "string",
      • "value": "string"
      }
    }
}
Invoices
A list of merchant invoices. Can include the total invoices count and HATEOAS links for navigation.


total_count
integer
The total number of invoices that match the search criteria.


 
Array of objects (Invoice) 
An array of invoice-level details.
Note: This array does not return item details for the invoice.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
{
  • "total_count": 0,
  • "invoices": [
    • {
      • "id": "string",
      • "number": "string",
      • "status": "DRAFT",
      • "billing_info": [
        • {
          • "email": "user@example.com",
          • "first_name": "string",
          • "last_name": "string",
          • "business_name": "string",
          • "language": "da_DK",
          • "additional_info": "string",
          • "phone": {
            • "country_code": "str",
            • "national_number": "string"
            },
          • "address": {
            • "line1": "string",
            • "line2": "string",
            • "city": "string",
            • "country_code": "string",
            • "postal_code": "string",
            • "state": "string",
            • "phone": "string"
            }
          }
        ],
      • "cc_info": [
        • {
          • "email": "user@example.com"
          }
        ],
      • "items": [
        • {
          • "name": "string",
          • "description": "string",
          • "quantity": 0,
          • "date": "2019-08-24",
          • "unit_of_measure": "QUANTITY",
          • "unit_price": {
            • "currency": "string",
            • "value": "string"
            },
          • "tax": {
            • "name": "string",
            • "percent": 0,
            • "amount": {
              • "currency": "string",
              • "value": "string"
              }
            },
          • "discount": {
            • "percent": 0,
            • "amount": {
              • "currency": "string",
              • "value": "string"
              }
            }
          }
        ],
      • "invoice_date": "2019-08-24",
      • "reference": "string",
      • "allow_partial_payment": false,
      • "tax_calculated_after_discount": false,
      • "tax_inclusive": false,
      • "terms": "string",
      • "note": "string",
      • "merchant_memo": "string",
      • "logo_url": "http://example.com",
      • "payments": [
        • {
          • "type": "PAYPAL",
          • "transaction_id": "string",
          • "transaction_type": "SALE",
          • "date": "2019-08-24T14:15:22Z",
          • "method": "BANK_TRANSFER",
          • "note": "string",
          • "amount": {
            • "currency": "string",
            • "value": "string"
            }
          }
        ],
      • "refunds": [
        • {
          • "type": "PAYPAL",
          • "transaction_id": "string",
          • "date": "2019-08-24T14:15:22Z",
          • "note": "string",
          • "amount": {
            • "currency": "string",
            • "value": "string"
            }
          }
        ],
      • "attachments": [],
      • "allow_tip": false,
      • "template_id": "PayPal system template",
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ],
      • "merchant_info": {
        • "email": "user@example.com",
        • "business_name": "string",
        • "first_name": "string",
        • "last_name": "string",
        • "website": "http://example.com",
        • "tax_id": "string",
        • "additional_info": "string",
        • "address": {
          • "line1": "string",
          • "line2": "string",
          • "city": "string",
          • "country_code": "string",
          • "postal_code": "string",
          • "state": "string",
          • "phone": "string"
          },
        • "phone": {
          • "country_code": "str",
          • "national_number": "string"
          },
        • "fax": {
          • "country_code": "str",
          • "national_number": "string"
          }
        },
      • "shipping_info": {
        • "first_name": "string",
        • "last_name": "string",
        • "business_name": "string",
        • "address": {
          • "line1": "string",
          • "line2": "string",
          • "city": "string",
          • "country_code": "string",
          • "postal_code": "string",
          • "state": "string",
          • "phone": "string"
          }
        },
      • "payment_term": {
        • "term_type": "DUE_ON_RECEIPT",
        • "due_date": "2019-08-24"
        },
      • "discount": {
        • "percent": 0,
        • "amount": {
          • "currency": "string",
          • "value": "string"
          }
        },
      • "shipping_cost": {
        • "amount": {
          • "currency": "string",
          • "value": "string"
          },
        • "tax": {
          • "name": "string",
          • "percent": 0,
          • "amount": {
            • "currency": "string",
            • "value": "string"
            }
          }
        },
      • "custom": {
        • "label": "string",
        • "amount": {
          • "currency": "string",
          • "value": "string"
          }
        },
      • "minimum_amount_due": {
        • "currency": "string",
        • "value": "string"
        },
      • "total_amount": {
        • "currency": "string",
        • "value": "string"
        },
      • "metadata": {
        • "created_date": "2019-08-24T14:15:22Z",
        • "created_by": "string",
        • "cancelled_date": "2019-08-24T14:15:22Z",
        • "cancelled_by": "string",
        • "last_updated_date": "2019-08-24T14:15:22Z",
        • "last_updated_by": "string",
        • "first_sent_date": "2019-08-24T14:15:22Z",
        • "last_sent_date": "2019-08-24T14:15:22Z",
        • "last_sent_by": "string",
        • "payer_view_url": "http://example.com"
        },
      • "paid_amount": {
        • "paypal": {
          • "currency": "string",
          • "value": "string"
          },
        • "other": {
          • "currency": "string",
          • "value": "string"
          }
        },
      • "refunded_amount": {
        • "paypal": {
          • "currency": "string",
          • "value": "string"
          },
        • "other": {
          • "currency": "string",
          • "value": "string"
          }
        }
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
merchant_info
The merchant business information that appears on the invoice.


email
string <email>   <= 260 characters 
The merchant email address. This email must be listed in the merchant's PayPal profile.
If you omit this value, notifications are sent from and to the primary email address but do not appear on the invoice.


 
business_name
string  <= 100 characters 
The merchant's business name.


 
first_name
string  <= 256 characters 
The merchant's first name.


 
last_name
string  <= 256 characters 
The merchant's last name.


 
website
string <uri>   <= 2048 characters 
The merchant's website.


 
tax_id
string  <= 100 characters 
The merchant's tax ID.


 
additional_info
string  <= 40 characters 
Any additional information, such as business hours.


 
object (Address) 
The address, which is either a billing address or shipping address in a payment.


 
object (Phone) 
The phone number.


 
object (Phone) 
The phone number.


 
{
  • "email": "user@example.com",
  • "business_name": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "website": "http://example.com",
  • "tax_id": "string",
  • "additional_info": "string",
  • "address": {
    • "line1": "string",
    • "line2": "string",
    • "city": "string",
    • "country_code": "string",
    • "postal_code": "string",
    • "state": "string",
    • "phone": "string"
    },
  • "phone": {
    • "country_code": "str",
    • "national_number": "string"
    },
  • "fax": {
    • "country_code": "str",
    • "national_number": "string"
    }
}
Metadata
The audit metadata.


created_date
string <date-time> 
The date and time when the resource was created, in Internet date and time format.


 
created_by
string
The email address of the account that created the resource.


 
cancelled_date
string <date-time> 
The date and time when the resource was canceled, in Internet date and time format.


 
cancelled_by
string
The actor who canceled the resource.


 
last_updated_date
string <date-time> 
The date and time when the resource was last edited, in Internet date and time format.


 
last_updated_by
string
The email address of the account that last edited the resource.


 
first_sent_date
string <date-time> 
The date and time when the resource was first sent, in Internet date and time format.


 
last_sent_date
string <date-time> 
The date and time when the resource was last sent, in Internet date and time format.


 
last_sent_by
string
The email address of the account that last sent the resource.


 
payer_view_url
string <uri> 
The URL for the payer's view of the invoice.


 
{
  • "created_date": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "cancelled_date": "2019-08-24T14:15:22Z",
  • "cancelled_by": "string",
  • "last_updated_date": "2019-08-24T14:15:22Z",
  • "last_updated_by": "string",
  • "first_sent_date": "2019-08-24T14:15:22Z",
  • "last_sent_date": "2019-08-24T14:15:22Z",
  • "last_sent_by": "string",
  • "payer_view_url": "http://example.com"
}
Notification
The email or SMS notification.


subject
string
The subject of the notification. Default is a generic subject.


 
note
string
A note to the payer.


 
send_to_merchant
boolean
 Default:  true
Indicates whether to send a copy of the email to the merchant.


 
cc_emails
Array of strings  <= 100 items 
An array of one or more CC: emails to which to send notification emails. If you omit this parameter, the API sends notification emails to all CC: email addresses that are part of the invoice.
Note: Valid values are email addresses in the cc_info array of the invoice.


 
{
  • "subject": "string",
  • "note": "string",
  • "send_to_merchant": true,
  • "cc_emails": [
    • "string"
    ]
}
Participant
The participant information.


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


 
{
  • "email": "user@example.com"
}
payment_detail
The payment details.


type
string
The payment type in an invoicing flow. The record refund method supports the EXTERNAL refund type. The PAYPAL refund type is supported for backward compatibility.


 Enum: "PAYPAL" "EXTERNAL"  
transaction_id
string
The ID for a PayPal payment transaction. Required for the PAYPAL payment type.


 
transaction_type
string
The transaction type.


 Enum: "SALE" "AUTHORIZATION" "CAPTURE"  
date
string <date-time> 
The date when the invoice was paid, in Internet date and time format.


 
method
required
string
The payment mode or method.


 Enum: "BANK_TRANSFER" "CASH" "CHECK" "CREDIT_CARD" "DEBIT_CARD" "PAYPAL" "WIRE_TRANSFER" "OTHER"  
note
string
A note associated with the payment.


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


 
{
  • "type": "PAYPAL",
  • "transaction_id": "string",
  • "transaction_type": "SALE",
  • "date": "2019-08-24T14:15:22Z",
  • "method": "BANK_TRANSFER",
  • "note": "string",
  • "amount": {
    • "currency": "string",
    • "value": "string"
    }
}
payment_summary
The payment and refund summary.


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


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


 
{
  • "paypal": {
    • "currency": "string",
    • "value": "string"
    },
  • "other": {
    • "currency": "string",
    • "value": "string"
    }
}
payment_term
The payment term of the invoice. If you specify term_type, you cannot specify due_date, and vice versa.


term_type
string
The term when the invoice payment is due.


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


 
{
  • "term_type": "DUE_ON_RECEIPT",
  • "due_date": "2019-08-24"
}
Phone
The phone number.


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


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


 
{
  • "country_code": "str",
  • "national_number": "string"
}
QR Code
The base64-encoded image of the image/png type.


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


 
{
  • "image": "string"
}
refund_detail
The invoicing refund details.


type
string
The PayPal refund type. Indicates whether the refund was paid through PayPal or externally in the invoicing flow. The record refund method supports the EXTERNAL refund type. The PAYPAL refund type is supported for backward compatibility.


 Enum: "PAYPAL" "EXTERNAL"  
transaction_id
string
The ID of the PayPal refund transaction. Required for the PAYPAL refund type.


 
date
string <date-time> 
The date when the invoice was refunded, in Internet date and time format. For example, 2014-02-27 PST.


 
note
string
A note associated with the refund.


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


 
{
  • "type": "PAYPAL",
  • "transaction_id": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "note": "string",
  • "amount": {
    • "currency": "string",
    • "value": "string"
    }
}
shipping_cost
The shipping cost, as a percent or amount value.


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


 
object (Tax) 
The tax information.


 
{
  • "amount": {
    • "currency": "string",
    • "value": "string"
    },
  • "tax": {
    • "name": "string",
    • "percent": 0,
    • "amount": {
      • "currency": "string",
      • "value": "string"
      }
    }
}
shipping_info
The shipping information for the invoice recipient.


first_name
string  <= 256 characters 
The first name of the recipient at the shipping address.


 
last_name
string  <= 256 characters 
The last name of the recipient at the shipping address.


 
business_name
string  <= 480 characters 
The business name of the recipient at the shipping address.


 
object (Address) 
The address, which is either a billing address or shipping address in a payment.


 
{
  • "first_name": "string",
  • "last_name": "string",
  • "business_name": "string",
  • "address": {
    • "line1": "string",
    • "line2": "string",
    • "city": "string",
    • "country_code": "string",
    • "postal_code": "string",
    • "state": "string",
    • "phone": "string"
    }
}
Summary
The summary of invoice data.


status
string
The invoice status. The status indicates the phase of the invoice in its lifecycle:
StatusOccurs 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:
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:
SCHEDULED
A merchant schedules an invoice to be emailed by PayPal on a specified date.
SENT
A merchant sends an invoice to the customer.
After the merchant sends the invoice:
  • PayPal emails the invoice to the customer.
  • A Payment button appears on the invoice. The customer can now pay the invoice.
  • In a web app, the invoice appears as Unpaid (sent).
UNPAID
A merchant sends an invoice and sets the notify_merchant and notify_customer query parameters to false to suppress the PayPal email notification. Then, the merchant manually sends the invoice link in his or her own email.


 Enum: "DRAFT" "SENT" "SCHEDULED" "PAID" "MARKED_AS_PAID" "CANCELLED" "REFUNDED" "PARTIALLY_REFUNDED" "MARKED_AS_REFUNDED" "UNPAID" "PAYMENT_PENDING"  
count
integer
The total count of invoices.


 
Array of objects (amount_summary) 
An array of amounts, grouped by the currency code of the invoice.


 
{
  • "status": "DRAFT",
  • "count": 0,
  • "amount_summary": [
    • {
      • "total_amount": {
        • "currency": "string",
        • "value": "string"
        },
      • "paid_amount": {
        • "paypal": {
          • "currency": "string",
          • "value": "string"
          },
        • "other": {
          • "currency": "string",
          • "value": "string"
          }
        },
      • "refunded_amount": {
        • "paypal": {
          • "currency": "string",
          • "value": "string"
          },
        • "other": {
          • "currency": "string",
          • "value": "string"
          }
        }
      }
    ]
}
Tax
The tax information.


name
required
string  <= 100 characters 
The tax name.


 
percent
required
number  >= 0 
The tax rate. Value is from 0 to 100. Supports up to five decimal places.


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


 
{
  • "name": "string",
  • "percent": 0,
  • "amount": {
    • "currency": "string",
    • "value": "string"
    }
}
Template
The invoicing template.


template_id
string
The ID of the template.


 
name
string
The template name.
Note: The template name must be unique.


 
default
boolean
Indicates whether this template is the default merchant template. A merchant can have one default template.


 
Array of objects (template_settings) 
An array of template settings that describe which fields to show or hide when creating an invoice.


 
unit_of_measure
string
The unit of measure for the template.


 Enum: "HOURS" "QUANTITY" "AMOUNT"  
custom
boolean
Indicates whether this template is a merchant-created custom template. The system generates non-custom templates.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
object (template_data) 
The template data.


 
{
  • "template_id": "string",
  • "name": "string",
  • "default": true,
  • "settings": [
    • {
      • "field_name": "items.quantity",
      • "display_preference": {
        • "hidden": false
        }
      }
    ],
  • "unit_of_measure": "HOURS",
  • "custom": true,
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "template_data": {
    • "billing_info": [
      • {
        • "email": "user@example.com",
        • "first_name": "string",
        • "last_name": "string",
        • "business_name": "string",
        • "language": "da_DK",
        • "additional_info": "string",
        • "phone": {
          • "country_code": "str",
          • "national_number": "string"
          },
        • "address": {
          • "line1": "string",
          • "line2": "string",
          • "city": "string",
          • "country_code": "string",
          • "postal_code": "string",
          • "state": "string",
          • "phone": "string"
          }
        }
      ],
    • "cc_info": [
      • "string"
      ],
    • "items": [
      • {
        • "name": "string",
        • "description": "string",
        • "quantity": 0,
        • "date": "2019-08-24",
        • "unit_of_measure": "QUANTITY",
        • "unit_price": {
          • "currency": "string",
          • "value": "string"
          },
        • "tax": {
          • "name": "string",
          • "percent": 0,
          • "amount": {
            • "currency": "string",
            • "value": "string"
            }
          },
        • "discount": {
          • "percent": 0,
          • "amount": {
            • "currency": "string",
            • "value": "string"
            }
          }
        }
      ],
    • "reference": "string",
    • "allow_partial_payment": false,
    • "tax_calculated_after_discount": false,
    • "tax_inclusive": false,
    • "terms": "string",
    • "note": "string",
    • "merchant_memo": "string",
    • "logo_url": "http://example.com",
    • "attachments": [],
    • "merchant_info": {
      • "email": "user@example.com",
      • "business_name": "string",
      • "first_name": "string",
      • "last_name": "string",
      • "website": "http://example.com",
      • "tax_id": "string",
      • "additional_info": "string",
      • "address": {
        • "line1": "string",
        • "line2": "string",
        • "city": "string",
        • "country_code": "string",
        • "postal_code": "string",
        • "state": "string",
        • "phone": "string"
        },
      • "phone": {
        • "country_code": "str",
        • "national_number": "string"
        },
      • "fax": {
        • "country_code": "str",
        • "national_number": "string"
        }
      },
    • "shipping_info": {
      • "first_name": "string",
      • "last_name": "string",
      • "business_name": "string",
      • "address": {
        • "line1": "string",
        • "line2": "string",
        • "city": "string",
        • "country_code": "string",
        • "postal_code": "string",
        • "state": "string",
        • "phone": "string"
        }
      },
    • "payment_term": {
      • "term_type": "DUE_ON_RECEIPT",
      • "due_date": "2019-08-24"
      },
    • "discount": {
      • "percent": 0,
      • "amount": {
        • "currency": "string",
        • "value": "string"
        }
      },
    • "shipping_cost": {
      • "amount": {
        • "currency": "string",
        • "value": "string"
        },
      • "tax": {
        • "name": "string",
        • "percent": 0,
        • "amount": {
          • "currency": "string",
          • "value": "string"
          }
        }
      },
    • "custom": {
      • "label": "string",
      • "amount": {
        • "currency": "string",
        • "value": "string"
        }
      },
    • "minimum_amount_due": {
      • "currency": "string",
      • "value": "string"
      },
    • "total_amount": {
      • "currency": "string",
      • "value": "string"
      }
    }
}
template_data
The template data.


Array of objects (billing_info)   = 1 items 
The billing information of the invoice recipient.
Note: This value is an array with only one element.


 
cc_info
Array of strings <email>  (Email) 
An array of email addresses to which PayPal sends a copy of the invoice.


 
Array of objects (invoice_item)   <= 100 items 
An array of invoice line item information. The maximum items for an invoice is 100.


 
reference
string  <= 60 characters 
The reference data, such as a PO number.


 
allow_partial_payment
boolean
 Default:  false
Indicates whether the invoice allows a partial payment. If false, the invoice must be paid in full. If true, the invoice allows partial payments.
Note: This feature is not available for merchants in India, Brazil, or Israel.


 
tax_calculated_after_discount
boolean
 Default:  false
Indicates whether the tax is calculated before or after a discount. If false, the tax is calculated before a discount. If true, the tax is calculated after a discount.


 
tax_inclusive
boolean
 Default:  false
Indicates whether the unit price includes tax.


 
terms
string  <= 4000 characters 
The general terms of the invoice.


 
note
string  <= 4000 characters 
A note to the invoice recipient. This note also appears on the invoice notification email.


 
merchant_memo
string  <= 150 characters 
A private bookkeeping memo for the merchant.


 
logo_url
string <uri>   <= 4000 characters 
The full URL to an external logo image. The logo image must not be larger than 250 pixels wide by 90 pixels high.


 
Array of objects (file_attachment) 
An array of PayPal file IDs for the files that are attached to an invoice. The maximum number of files is 5.


 
required
object (merchant_info) 
The merchant business information that appears on the invoice.


 
object (shipping_info) 
The shipping information for the invoice recipient.


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


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


 
object (shipping_cost) 
The shipping cost, as a percent or amount value.


 
object (custom_amount) 
The custom amount to apply to an invoice. If you include a label, you must include a custom amount.


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


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


 
{
  • "billing_info": [
    • {
      • "email": "user@example.com",
      • "first_name": "string",
      • "last_name": "string",
      • "business_name": "string",
      • "language": "da_DK",
      • "additional_info": "string",
      • "phone": {
        • "country_code": "str",
        • "national_number": "string"
        },
      • "address": {
        • "line1": "string",
        • "line2": "string",
        • "city": "string",
        • "country_code": "string",
        • "postal_code": "string",
        • "state": "string",
        • "phone": "string"
        }
      }
    ],
  • "cc_info": [
    • "string"
    ],
  • "items": [
    • {
      • "name": "string",
      • "description": "string",
      • "quantity": 0,
      • "date": "2019-08-24",
      • "unit_of_measure": "QUANTITY",
      • "unit_price": {
        • "currency": "string",
        • "value": "string"
        },
      • "tax": {
        • "name": "string",
        • "percent": 0,
        • "amount": {
          • "currency": "string",
          • "value": "string"
          }
        },
      • "discount": {
        • "percent": 0,
        • "amount": {
          • "currency": "string",
          • "value": "string"
          }
        }
      }
    ],
  • "reference": "string",
  • "allow_partial_payment": false,
  • "tax_calculated_after_discount": false,
  • "tax_inclusive": false,
  • "terms": "string",
  • "note": "string",
  • "merchant_memo": "string",
  • "logo_url": "http://example.com",
  • "attachments": [],
  • "merchant_info": {
    • "email": "user@example.com",
    • "business_name": "string",
    • "first_name": "string",
    • "last_name": "string",
    • "website": "http://example.com",
    • "tax_id": "string",
    • "additional_info": "string",
    • "address": {
      • "line1": "string",
      • "line2": "string",
      • "city": "string",
      • "country_code": "string",
      • "postal_code": "string",
      • "state": "string",
      • "phone": "string"
      },
    • "phone": {
      • "country_code": "str",
      • "national_number": "string"
      },
    • "fax": {
      • "country_code": "str",
      • "national_number": "string"
      }
    },
  • "shipping_info": {
    • "first_name": "string",
    • "last_name": "string",
    • "business_name": "string",
    • "address": {
      • "line1": "string",
      • "line2": "string",
      • "city": "string",
      • "country_code": "string",
      • "postal_code": "string",
      • "state": "string",
      • "phone": "string"
      }
    },
  • "payment_term": {
    • "term_type": "DUE_ON_RECEIPT",
    • "due_date": "2019-08-24"
    },
  • "discount": {
    • "percent": 0,
    • "amount": {
      • "currency": "string",
      • "value": "string"
      }
    },
  • "shipping_cost": {
    • "amount": {
      • "currency": "string",
      • "value": "string"
      },
    • "tax": {
      • "name": "string",
      • "percent": 0,
      • "amount": {
        • "currency": "string",
        • "value": "string"
        }
      }
    },
  • "custom": {
    • "label": "string",
    • "amount": {
      • "currency": "string",
      • "value": "string"
      }
    },
  • "minimum_amount_due": {
    • "currency": "string",
    • "value": "string"
    },
  • "total_amount": {
    • "currency": "string",
    • "value": "string"
    }
}
template_settings
The template settings.


field_name
string
The field name in template_data for which to map corresponding display preferences.


 Enum: "items.quantity" "items.description" "items.date" "items.discount" "items.tax" "discount" "shipping" "custom"  
object (template_settings_metadata) 
The template settings metadata.


 
{
  • "field_name": "items.quantity",
  • "display_preference": {
    • "hidden": false
    }
}
template_settings_metadata
The template settings metadata.


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


 
{
  • "hidden": false
}
Templates
A merchant-created template with associated details. The associated details include the emails, addresses, and phone numbers from the user's PayPal profile.


Array of objects (Address) 
An array of postal addresses in the user's PayPal profile.


 
emails
Array of strings
An array of email addresses in the user's PayPal profile.


 
Array of objects (Phone) 
An array of phone numbers in the user's PayPal profile.


 
Array of objects (Template) 
The details for each template. If fields is none, returns only the template name, ID, and default status.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
{
  • "addresses": [
    • {
      • "line1": "string",
      • "line2": "string",
      • "city": "string",
      • "country_code": "string",
      • "postal_code": "string",
      • "state": "string",
      • "phone": "string"
      }
    ],
  • "emails": [
    • "string"
    ],
  • "phones": [
    • {
      • "country_code": "str",
      • "national_number": "string"
      }
    ],
  • "templates": [
    • {
      • "template_id": "string",
      • "name": "string",
      • "default": true,
      • "settings": [
        • {
          • "field_name": "items.quantity",
          • "display_preference": {
            • "hidden": false
            }
          }
        ],
      • "unit_of_measure": "HOURS",
      • "custom": true,
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ],
      • "template_data": {
        • "billing_info": [
          • {
            • "email": "user@example.com",
            • "first_name": "string",
            • "last_name": "string",
            • "business_name": "string",
            • "language": "da_DK",
            • "additional_info": "string",
            • "phone": {
              • "country_code": "str",
              • "national_number": "string"
              },
            • "address": {
              • "line1": "string",
              • "line2": "string",
              • "city": "string",
              • "country_code": "string",
              • "postal_code": "string",
              • "state": "string",
              • "phone": "string"
              }
            }
          ],
        • "cc_info": [
          • "string"
          ],
        • "items": [
          • {
            • "name": "string",
            • "description": "string",
            • "quantity": 0,
            • "date": "2019-08-24",
            • "unit_of_measure": "QUANTITY",
            • "unit_price": {
              • "currency": "string",
              • "value": "string"
              },
            • "tax": {
              • "name": "string",
              • "percent": 0,
              • "amount": {
                • "currency": null,
                • "value": null
                }
              },
            • "discount": {
              • "percent": 0,
              • "amount": {
                • "currency": null,
                • "value": null
                }
              }
            }
          ],
        • "reference": "string",
        • "allow_partial_payment": false,
        • "tax_calculated_after_discount": false,
        • "tax_inclusive": false,
        • "terms": "string",
        • "note": "string",
        • "merchant_memo": "string",
        • "logo_url": "http://example.com",
        • "attachments": [],
        • "merchant_info": {
          • "email": "user@example.com",
          • "business_name": "string",
          • "first_name": "string",
          • "last_name": "string",
          • "website": "http://example.com",
          • "tax_id": "string",
          • "additional_info": "string",
          • "address": {
            • "line1": "string",
            • "line2": "string",
            • "city": "string",
            • "country_code": "string",
            • "postal_code": "string",
            • "state": "string",
            • "phone": "string"
            },
          • "phone": {
            • "country_code": "str",
            • "national_number": "string"
            },
          • "fax": {
            • "country_code": "str",
            • "national_number": "string"
            }
          },
        • "shipping_info": {
          • "first_name": "string",
          • "last_name": "string",
          • "business_name": "string",
          • "address": {
            • "line1": "string",
            • "line2": "string",
            • "city": "string",
            • "country_code": "string",
            • "postal_code": "string",
            • "state": "string",
            • "phone": "string"
            }
          },
        • "payment_term": {
          • "term_type": "DUE_ON_RECEIPT",
          • "due_date": "2019-08-24"
          },
        • "discount": {
          • "percent": 0,
          • "amount": {
            • "currency": "string",
            • "value": "string"
            }
          },
        • "shipping_cost": {
          • "amount": {
            • "currency": "string",
            • "value": "string"
            },
          • "tax": {
            • "name": "string",
            • "percent": 0,
            • "amount": {
              • "currency": "string",
              • "value": "string"
              }
            }
          },
        • "custom": {
          • "label": "string",
          • "amount": {
            • "currency": "string",
            • "value": "string"
            }
          },
        • "minimum_amount_due": {
          • "currency": "string",
          • "value": "string"
          },
        • "total_amount": {
          • "currency": "string",
          • "value": "string"
          }
        }
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}