Create Draft Invoice

Drafting an invoice creates an unpublished invoice that is viewable only by the merchant. When sending the draft invoice request, set the invoiceInformation.deliveryMode field to none to ensure that the invoice draft is not automatically sent in an email message to the customer when the invoice is published. When you are ready to publish the draft invoice, you can send a send invoice request. After publishing the drafted invoice, the invoice's status updates from DRAFT to CREATED. The created invoice is then shareable with the customer.

A successfully drafted invoice is indicated by the DRAFT status in the status response field.

The redirect URL generated in the invoiceInformation.paymentLink response field is usable only by the merchant, not the customer.

Follow-on operations: Send Invoice, Update Invoice, Cancel Invoice, Get Invoice Details, Get Invoices

Draft an In-Person Invoice

Endpoint

POST /invoicing/v2/invoices

Example

{  "invoiceInformation": {    "description": "Food",    "dueDate": "2019-07-11",    "sendImmediately": false,    "deliveryMode": "none"  },  "orderInformation": {    "amountDetails": {      "totalAmount": "2623.64",      "currency": "USD"    }  }}

{  "_links": {    "self": {      "href": "/v2/invoices/98762",      "method": "GET"    },    "update": {      "href": "/v2/invoices/98762",      "method": "PUT"    },    "deliver": {      "href": "/v2/invoices/98762/delivery",      "method": "POST"    },    "cancel": {      "href": "/v2/invoices/98762/cancelation",      "method": "POST"    }  },  "id": "98762",  "submitTimeUtc": "2024-08-02T19:24:06.184293960Z",  "status": "CREATED",  "processingInformation": {    "requestPhone": false,    "requestShipping": false  },  "invoiceInformation": {    "invoiceNumber": "98762",    "description": "Food",    "dueDate": "2019-07-11",    "allowPartialPayments": false,    "paymentLink": "/ebc2/invoicing/payInvoice/NyvghJCpsrrZAjkvZNxelqUrI7iyOdLXFXWS8e5MLXyLYbifinsuYfBk6kaYo3co?version=v2.1",    "deliveryMode": "None"  },  "orderInformation": {    "amountDetails": {      "totalAmount": 2623.64,      "currency": "USD",      "balanceAmount": 2623.64    }  }}

Required Fields

Field	Type	Description
`invoiceInformation.deliveryMode`	string	Set to one of these possible values to determine whether the invoice is emailed to the customer when you send a send invoice request: `email` (an invoice email is sent to the customer when you send the follow-on send invoice request for this invoice draft; the invoice status updates to `SENT`), or `none` (when you process a follow-on send invoice request to publish the drafted invoice, the invoice is not sent in an email to the customer; to share the invoice with the customer, send the customer the redirect URL in the `invoiceInformation.paymentLink` response field; the invoice updates change to `CREATED`).
`invoiceInformation.description`	string	Customer-facing description of the invoice. Optional when `orderInformation.lineItems[]` fields are included.
`invoiceInformation.dueDate`	string	The date payment is due. Format: `YYYY-MM-DD`.
`invoiceInformation.sendImmediately`	boolean	Set to `false`.
`orderInformation.amountDetails.currency`	string	ISO 4217 three-letter currency code for the invoice.
`orderInformation.amountDetails.totalAmount`	string	The total charge amount for the invoice, as a decimal string.

Draft an Email Invoice

Endpoint

POST /invoicing/v2/invoices

Required Fields

Field	Type	Description
`customerInformation.email`	string	Customer's email address. The invoice is sent to this address.
`customerInformation.name`	string	Customer's full name as it appears on the invoice.
`invoiceInformation.deliveryMode`	string	Set to `email`.
`invoiceInformation.description`	string	Customer-facing description of the invoice. Optional when `orderInformation.lineItems[]` fields are included.
`invoiceInformation.dueDate`	string	The date payment is due. Format: `YYYY-MM-DD`.
`invoiceInformation.sendImmediately`	boolean	Set to `false`.
`orderInformation.amountDetails.currency`	string	ISO 4217 three-letter currency code for the invoice.
`orderInformation.amountDetails.totalAmount`	string	The total charge amount for the invoice, as a decimal string.

Draft an Invoice with Line Items

Endpoint

POST /invoicing/v2/invoices

Example

{  "customerInformation": {    "name": "Tanya Lee",    "email": "[email protected]"  },  "invoiceInformation": {    "dueDate": "2019-07-11",    "sendImmediately": false,    "deliveryMode": "none"  },  "orderInformation": {    "amountDetails": {      "totalAmount": "293.50",      "currency": "USD"    },    "lineItems": [      {        "productSku": "P653727383",        "productName": "First line item's name",        "quantity": "20",        "unitPrice": "12.05",        "totalAmount": "241.00"      },      {        "productSku": "P653727383",        "productName": "First line item's name",        "quantity": "10",        "unitPrice": "5.25",        "totalAmount": "52.50"      }    ]  }}

{  "_links": {    "self": {      "href": "/v2/invoices/98764",      "method": "GET"    },    "update": {      "href": "/v2/invoices/98764",      "method": "PUT"    },    "deliver": {      "href": "/v2/invoices/98764/delivery",      "method": "POST"    },    "cancel": {      "href": "/v2/invoices/98764/cancelation",      "method": "POST"    }  },  "id": "98764",  "submitTimeUtc": "2024-08-02T22:14:13.000671718Z",  "status": "DRAFT",  "customerInformation": {    "name": "Tanya Lee",    "email": "[email protected]"  },  "processingInformation": {    "requestPhone": false,    "requestShipping": false  },  "invoiceInformation": {    "invoiceNumber": "98764",    "dueDate": "2019-07-11",    "allowPartialPayments": false,    "deliveryMode": "None"  },  "orderInformation": {    "amountDetails": {      "totalAmount": 293.5,      "currency": "USD"    },    "lineItems": [      {        "productSku": "P653727383",        "productName": "First line item's name",        "unitPrice": 12.05,        "quantity": 20,        "totalAmount": 241      },      {        "productSku": "P653727383",        "productName": "First line item's name",        "unitPrice": 5.25,        "quantity": 10,        "totalAmount": 52.5      }    ]  }}

Required Fields

Field	Type	Description
`customerInformation.email`	string	Customer's email address. The invoice is sent to this address.
`customerInformation.name`	string	Customer's full name as it appears on the invoice.
`invoiceInformation.deliveryMode`	string	Set to one of these possible values to determine whether the invoice is emailed to the customer when you send a send invoice request: `email` (an invoice email is sent to the customer when you send the follow-on send invoice request for this invoice draft; the invoice status changes to `SENT`), or `none` (when you process a follow-on send invoice request to publish the drafted invoice, the invoice is not sent in an email to the customer; to share the invoice with the customer, send the customer the redirect URL in the `invoiceInformation.paymentLink` response field; the invoice status changes to `CREATED`).
`invoiceInformation.dueDate`	string	The date payment is due. Format: `YYYY-MM-DD`.
`invoiceInformation.sendImmediately`	boolean	Set to `false`.
`orderInformation.amountDetails.currency`	string	ISO 4217 three-letter currency code for the invoice.
`orderInformation.amountDetails.totalAmount`	string	The total charge amount for the invoice, as a decimal string.
`orderInformation.lineItems[].productName`	string	Display name of the line item as it appears on the invoice.
`orderInformation.lineItems[].productSku`	string	Stock-keeping unit identifier for this line item.
`orderInformation.lineItems[].quantity`	integer	Number of units for this line item.
`orderInformation.lineItems[].totalAmount`	number	Total amount for this line item.
`orderInformation.lineItems[].unitPrice`	number	Price per unit for this line item.

Optional Fields

You can include these optional fields when sending create invoice requests:

Optional Fields

Field	Type	Description
`clientReferenceInformation.partner.developerId`	string	Set to your developer ID.
`clientReferenceInformation.partner.solutionId`	string	Set to your partner solution ID (PSID).
`customerInformation.company.name`	string	Customer's company name as it appears on the invoice.
`customerInformation.email`	string	Customer's email address.
`customerInformation.merchantCustomerId`	string	Your identifier for this customer in your system.
`customerInformation.name`	string	Customer's full name as it appears on the invoice.
`invoiceInformation.allowPartialPayments`	boolean	Set to one of these possible values: `false` (the invoice must be paid in a single payment), or `true` (the invoice is payable in installments).
`invoiceInformation.deliveryMode`	string	Set to `email` to email the invoice to the customer, or `none` to create a payable link without sending an email.
`invoiceInformation.description`	string	This field is optional when the line item fields are present in the request message.
`invoiceInformation.expirationDate`	string	Set to the expiration date. Format: `YYYY-MM-DD`. The invoice expires on this date at 00:00 UTC.
`invoiceInformation.invoiceNumber`	string	Set to a unique number to create an invoice number. If you do not include this field and a unique value, the invoicing API automatically generates an invoice number for the new invoice. You cannot update this invoice number after sending the API request.
`merchantDefinedFieldValues.definition id[].value`	string	Value for a merchant-defined custom field.
`orderInformation.amountDetails.freight.amount`	number	Freight or shipping amount added to the invoice total.
`orderInformation.amountDetails.freight.taxable`	boolean	Set to `true` if freight is subject to tax.
`orderInformation.amountDetails.freight.taxRate`	number	Tax rate applied to the freight amount.
`orderInformation.amountDetails.minimumPartialAmount`	number	The minimum amount allowed for a single installment payment. Only applies when `allowPartialPayments` is `true`.
`orderInformation.amountDetails.subAmount`	number	The subtotal before discounts or tax adjustments.

Was this page helpful?

Last published: September 29, 2026