Create draft invoice

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.

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.

numberstringOptional

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

Length0 <= length <= 25

merchant_infoobject<merchant-info>Required

The merchant information, such as business name, email, address, and so on.

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

An array of billing information for 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 recipient of the invoice.

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_infoobject<participant>[]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.

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"

invoice_datestringOptional

The invoice date as specified by the sender, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).

Formatdate

payment_termobject<payment-term>Optional

The payment due date of the invoice. If you include `due_date`, the `term_type` value is ignored.

referencestringOptional

The reference data, such as 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 amount, 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 minimum amount allowed for a partial payment. Valid only if `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. The note also appears on the invoice notification email.

Length0 <= length <= 4000

merchant_memostringOptional

A private bookkeeping memo for the merchant.

Length0 <= length <= 500

logo_urlstringOptional

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.

FormaturiLength0 <= length <= 4000

allow_tipbooleanOptional

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

Defaultfalse

template_idstringOptional

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.

Default"PayPal system template"

Response Body

`application/json`

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

{  "id": "string",  "number": "string",  "status": "DRAFT",  "merchant_info": {    "email": "[email protected]",    "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": "[email protected]",      "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": [    {      "email": "[email protected]"    }  ],  "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"    }  ],  "invoice_date": "2019-08-24",  "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"  },  "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"      }    }  ],  "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"    }  },  "attachments": [    {      "name": "string",      "url": "http://example.com"    }  ],  "allow_tip": false,  "template_id": "PayPal system template",  "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"      }    }  ]}

{ "id": "string", "number": "string", "status": "DRAFT", "merchant_info": { "email": "[email protected]", "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": "[email protected]", "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": [ { "email": "[email protected]" } ], "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" } ], "invoice_date": "2019-08-24", "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" }, "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" } } ], "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" } }, "attachments": [ { "name": "string", "url": "http://example.com" } ], "allow_tip": false, "template_id": "PayPal system template", "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

merchant-info properties

address properties

phone properties

phone properties

billing-info properties

phone properties

address properties

shipping-info properties

address properties

participant 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

Response Body

201application/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 draft invoice

Authorization

Request Body

merchant-info properties

address properties

phone properties

phone properties

billing-info properties

phone properties

address properties

shipping-info properties

address properties

participant 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

Response Body

201application/json

defaultapplication/json

On this page

On this page

`application/json`

`application/json`

`application/json`

`application/json`