Create template

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`.

Authorization

AuthorizationBearer <token>

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

Manage invoice resource.https://uri.paypal.com/services/invoicing

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

namestringOptional

The template name.

Note: The template name must be unique.

defaultbooleanOptional

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

template_dataobject<template-data>Optional

The template data.

template-data properties

19 properties

merchant_infoobject<merchant-info>Required

The merchant business information that appears on the invoice.

merchant-info properties

10 properties

emailstringOptional

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.

FormatemailLength0 <= length <= 260

business_namestringOptional

The merchant's business name.

Length0 <= length <= 100

first_namestringOptional

The merchant's first name.

Length0 <= length <= 256

last_namestringOptional

The merchant's last name.

Length0 <= length <= 256

addressobject<address>Optional

The merchant's address.

phoneobject<phone>Optional

The merchant's phone number.

faxobject<phone>Optional

The merchant's fax number.

websitestringOptional

The merchant's website.

FormaturiLength0 <= length <= 2048

tax_idstringOptional

The merchant's tax ID.

Length0 <= length <= 100

additional_infostringOptional

Any additional information, such as business hours.

Length0 <= length <= 40

billing_infoobject<billing-info>[]Optional

The billing information of the invoice recipient.

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

Items1 <= length <= 1

billing-info properties

8 properties

emailstringOptional

The invoice recipient email address. If you omit this value, the invoice is payable and a notification email is not sent.

FormatemailLength0 <= length <= 260

phoneobject<phone>Optional

The invoice recipient's phone number.

first_namestringOptional

The invoice recipient's first name.

Length0 <= length <= 30

last_namestringOptional

The invoice recipient's last name.

Length0 <= length <= 30

business_namestringOptional

The invoice recipient's business name.

Length0 <= length <= 100

addressobject<address>Optional

The invoice recipient's billing address.

languageenumOptional

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

additional_infostringOptional

Any additional information about the recipient.

Length0 <= length <= 40

shipping_infoobject<shipping-info>Optional

The shipping information for the invoice recipient.

shipping-info properties

4 properties

first_namestringOptional

The first name of the recipient at the shipping address.

Length0 <= length <= 256

last_namestringOptional

The last name of the recipient at the shipping address.

Length0 <= length <= 256

business_namestringOptional

The business name of the recipient at the shipping address.

Length0 <= length <= 480

addressobject<address>Optional

The shipping address.

cc_infoarray<email>Optional

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

itemsobject<invoice-item>[]Optional

An array of invoice line item information. The maximum items for an invoice is `100`.

Items0 <= length <= 100

invoice-item properties

8 properties

namestringRequired

The item name.

Length0 <= length <= 200

descriptionstringOptional

The item description.

Length0 <= length <= 1000

quantitynumberRequired

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

unit_priceobject<currency>Required

The currency and amount of the item unit price. Value is from `-1000000` to `1000000`. Supports up to two decimal places.

taxobject<tax>Optional

The tax information.

datestringOptional

The date when the item or service was provided, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd* *z*.

Formatdate

discountobject<discount>Optional

The item discount, as a percent or an amount value.

unit_of_measureenumOptional

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.

Value in"QUANTITY" | "HOURS" | "AMOUNT"

payment_termobject<payment-term>Optional

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

referencestringOptional

The reference data, such as a PO number.

Length0 <= length <= 60

discountobject<discount>Optional

The invoice level discount, as a percent or an amount value.

shipping_costobject<shipping-cost>Optional

The shipping cost, as a percent or an amount value.

customobject<custom-amount>Optional

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

allow_partial_paymentbooleanOptional

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`.

Defaultfalse

minimum_amount_dueobject<currency>Optional

The currency and amount of the minimum allowed for a partial payment. Valid only when `allow_partial_payment` is `true`.

tax_calculated_after_discountbooleanOptional

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.

Defaultfalse

tax_inclusivebooleanOptional

Indicates whether the unit price includes tax.

Defaultfalse

termsstringOptional

The general terms of the invoice.

Length0 <= length <= 4000

notestringOptional

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

Length0 <= length <= 4000

merchant_memostringOptional

A private bookkeeping memo for the merchant.

Length0 <= length <= 150

logo_urlstringOptional

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

FormaturiLength0 <= length <= 4000

attachmentsobject<file-attachment>[]Optional

An array of PayPal file IDs for the files that are attached to an invoice. The maximum number of files is `5`.

settingsobject<template-settings>[]Optional

An array of template settings that describe which fields to show or hide when creating an invoice.

unit_of_measureenumOptional

The unit of measure for the template.

Value in"HOURS" | "QUANTITY" | "AMOUNT"

Response Body

`application/json`

curl -X POST "https://example.com/v1/invoicing/templates" \  -H "Content-Type: application/json" \  -d '{}'

{  "template_id": "string",  "name": "string",  "default": true,  "template_data": {    "merchant_info": {      "email": "user@example.com",      "business_name": "string",      "first_name": "string",      "last_name": "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"      },      "website": "http://example.com",      "tax_id": "string",      "additional_info": "string"    },    "billing_info": [      {        "email": "user@example.com",        "phone": {          "country_code": "str",          "national_number": "string"        },        "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"        },        "language": "da_DK",        "additional_info": "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"      }    },    "cc_info": [      "user@example.com"    ],    "items": [      {        "name": "string",        "description": "string",        "quantity": 0,        "unit_price": {          "currency": "string",          "value": "string"        },        "tax": {          "name": "string",          "percent": 0,          "amount": {            "currency": "string",            "value": "string"          },          "tax_note": "string"        },        "date": "2019-08-24",        "discount": {          "percent": 0,          "amount": {            "currency": "string",            "value": "string"          }        },        "unit_of_measure": "QUANTITY"      }    ],    "payment_term": {      "term_type": "DUE_ON_RECEIPT",      "due_date": "2019-08-24"    },    "reference": "string",    "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"        },        "tax_note": "string"      }    },    "custom": {      "label": "string",      "amount": {        "currency": "string",        "value": "string"      }    },    "allow_partial_payment": false,    "minimum_amount_due": {      "currency": "string",      "value": "string"    },    "tax_calculated_after_discount": false,    "tax_inclusive": false,    "terms": "string",    "note": "string",    "merchant_memo": "string",    "logo_url": "http://example.com",    "total_amount": {      "currency": "string",      "value": "string"    },    "attachments": [      {        "name": "string",        "url": "http://example.com"      }    ]  },  "settings": [    {      "field_name": "items.quantity",      "display_preference": {        "hidden": false      }    }  ],  "unit_of_measure": "HOURS",  "custom": true,  "links": [    {      "href": "string",      "rel": "string",      "method": "GET",      "title": "string",      "mediaType": "string",      "encType": "application/json",      "schema": {        "additionalItems": {},        "dependencies": {},        "items": {},        "patternProperties": {},        "properties": {},        "allOf": [          {}        ],        "anyOf": [          {}        ],        "oneOf": [          {}        ],        "not": {},        "links": [          {}        ],        "fragmentResolution": "string",        "media": {          "type": "string",          "binaryEncoding": "string"        },        "pathStart": "http://example.com"      },      "targetSchema": {        "additionalItems": {},        "dependencies": {},        "items": {},        "patternProperties": {},        "properties": {},        "allOf": [          {}        ],        "anyOf": [          {}        ],        "oneOf": [          {}        ],        "not": {},        "links": [          {}        ],        "fragmentResolution": "string",        "media": {          "type": "string",          "binaryEncoding": "string"        },        "pathStart": "http://example.com"      }    }  ]}

{ "template_id": "string", "name": "string", "default": true, "template_data": { "merchant_info": { "email": "user@example.com", "business_name": "string", "first_name": "string", "last_name": "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" }, "website": "http://example.com", "tax_id": "string", "additional_info": "string" }, "billing_info": [ { "email": "user@example.com", "phone": { "country_code": "str", "national_number": "string" }, "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" }, "language": "da_DK", "additional_info": "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" } }, "cc_info": [ "user@example.com" ], "items": [ { "name": "string", "description": "string", "quantity": 0, "unit_price": { "currency": "string", "value": "string" }, "tax": { "name": "string", "percent": 0, "amount": { "currency": "string", "value": "string" }, "tax_note": "string" }, "date": "2019-08-24", "discount": { "percent": 0, "amount": { "currency": "string", "value": "string" } }, "unit_of_measure": "QUANTITY" } ], "payment_term": { "term_type": "DUE_ON_RECEIPT", "due_date": "2019-08-24" }, "reference": "string", "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" }, "tax_note": "string" } }, "custom": { "label": "string", "amount": { "currency": "string", "value": "string" } }, "allow_partial_payment": false, "minimum_amount_due": { "currency": "string", "value": "string" }, "tax_calculated_after_discount": false, "tax_inclusive": false, "terms": "string", "note": "string", "merchant_memo": "string", "logo_url": "http://example.com", "total_amount": { "currency": "string", "value": "string" }, "attachments": [ { "name": "string", "url": "http://example.com" } ] }, "settings": [ { "field_name": "items.quantity", "display_preference": { "hidden": false } } ], "unit_of_measure": "HOURS", "custom": true, "links": [ { "href": "string", "rel": "string", "method": "GET", "title": "string", "mediaType": "string", "encType": "application/json", "schema": { "additionalItems": {}, "dependencies": {}, "items": {}, "patternProperties": {}, "properties": {}, "allOf": [ {} ], "anyOf": [ {} ], "oneOf": [ {} ], "not": {}, "links": [ {} ], "fragmentResolution": "string", "media": { "type": "string", "binaryEncoding": "string" }, "pathStart": "http://example.com" }, "targetSchema": { "additionalItems": {}, "dependencies": {}, "items": {}, "patternProperties": {}, "properties": {}, "allOf": [ {} ], "anyOf": [ {} ], "oneOf": [ {} ], "not": {}, "links": [ {} ], "fragmentResolution": "string", "media": { "type": "string", "binaryEncoding": "string" }, "pathStart": "http://example.com" } } ]}

Authorization

Request Body

template-data properties

merchant-info properties

address properties

phone properties

phone properties

billing-info properties

phone properties

address properties

shipping-info properties

address properties

invoice-item properties

currency properties

tax properties

discount properties

currency properties

payment-term properties

discount properties

currency properties

shipping-cost properties

currency properties

tax properties

custom-amount properties

currency properties

currency properties

file-attachment properties

template-settings properties

template-settings-metadata properties

Response Body

200application/json

defaultapplication/json

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Create template

Authorization

Request Body

template-data properties

merchant-info properties

address properties

phone properties

phone properties

billing-info properties

phone properties

address properties

shipping-info properties

address properties

invoice-item properties

currency properties

tax properties

discount properties

currency properties

payment-term properties

discount properties

currency properties

shipping-cost properties

currency properties

tax properties

custom-amount properties

currency properties

currency properties

file-attachment properties

template-settings properties

template-settings-metadata properties

Response Body

200application/json

defaultapplication/json

On this page

On this page

`application/json`

`application/json`

`application/json`

`application/json`