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: 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
201

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

Request samples
application/json
{
  • "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.

Responses
200

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

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/invoicing/invoices?page=3&page_size=4&total_count_required=true \
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.

Responses
202

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

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-EHNV-LJ5S-A7DZ-V6NJ/send?notify_merchant=true \

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.

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 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-EHNV-LJ5S-A7DZ-V6NJ/schedule \
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: application/json
subject
string

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

note
string

A note to the payer.

send_to_merchant
boolean
Default: true

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

cc_emails
Array of strings <= 100 items

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

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

Responses
202

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

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

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: application/json
subject
string

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

note
string

A note to the payer.

send_to_merchant
boolean
Default: true

Indicates whether to send the notification to the merchant.

send_to_payer
boolean
Default: true

Indicates whether to send the notification to the payer.

cc_emails
Array of strings <= 100 items

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

Note: Additional email addresses are not supported.

Responses
204

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

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

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: application/json
date
string <date-time>

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

method
required
string

The payment mode or method.

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

A note associated with the payment.

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
application/json
{
  • "method": "CASH",
  • "date": "2013-11-06 03:30:00 PST",
  • "note": "I got the payment by cash!",
  • "amount": {
    • "currency": "USD",
    • "value": "20.00"
    }
}

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: application/json
date
string <date-time>

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

note
string

A note associated with the refund.

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
application/json
{
  • "date": "2013-11-10 14:00:00 PST",
  • "note": "Refunded by cash!",
  • "amount": {
    • "currency": "USD",
    • "value": "20.00"
    }
}

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 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7 \
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 
curl -v -X DELETE https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-92MG-CNXV-ND7G-P3D2 \

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

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

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 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-S6FG-ZZCK-VXMM-8KKP/qr-code \
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
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 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/invoicing/invoices/next-invoice-number \
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: 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
201

Created

Request samples
application/json
{
  • "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.

Responses
200

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

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/invoicing/templates \
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