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

Endpoint

POST /invoicing/v2/invoices

Examples

{  "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    }  }}

{  "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

Required Fields: Draft an In-Person 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 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.

Required Fields: Draft an Email Invoice

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.

Required Fields: Draft an Invoice with Line Items

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

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: October 28, 2026

Endpoint

Examples

Required Fields

Optional Fields

Not available for your audience