Partnerships
Sign In
Sign In

API Explorer

You are viewing an old version of the API

All Versions

Create invoice

POST /v2/invoices

Creates a draft invoice for an order created using the Orders API.

Open in API Reference

Access Tokens Sign in to populate your access tokens from the developer dashboard Sign In

Body

invoice

The invoice to create.

Invoice

accepted_payment_methods

The payment methods that customers can use to pay the invoice on the Square-hosted invoice page. This setting is independent of any automatic payment requests for the invoice.

This field is required when creating an invoice and must set at least one payment method to true.

InvoiceAcceptedPaymentMethods

bank_account

Indicates whether ACH bank transfer payments are accepted. The default value is false.

boolean

buy_now_pay_later

Indicates whether Afterpay (also known as Clearpay) payments are accepted. The default value is false.

This option is allowed only for invoices that have a single payment request of the BALANCE type. This payment method is supported if the seller account accepts Afterpay payments and the seller location is in a country where Afterpay invoice payments are supported. As a best practice, consider enabling an additional payment method when allowing buy_now_pay_later payments. For more information, including detailed requirements and processing limits, see Buy Now Pay Later payments with Afterpay.

boolean

card

Indicates whether credit card or debit card payments are accepted. The default value is false.

boolean

cash_app_pay

Indicates whether Cash App payments are accepted. The default value is false.

This payment method is supported only for seller locations in the United States.

boolean

square_gift_card

Indicates whether Square gift card payments are accepted. The default value is false.

boolean

custom_fields

Additional seller-defined fields that are displayed on the invoice. For more information, see Custom fields.

Adding custom fields to an invoice requires an Invoices Plus subscription.

Max: 2 custom fields

Max Length 2

InvoiceCustomField [ ]

delivery_method

The delivery method that Square uses to send the invoice, reminders, and receipts to the customer. After the invoice is published, Square processes the invoice based on the delivery method and payment request settings, either immediately or on the scheduled_at date, if specified. For example, Square might send the invoice or receipt for an automatic payment. For invoices with automatic payments, this field must be set to EMAIL.

One of the following is required when creating an invoice:

(Recommended) This delivery_method field. To configure an automatic payment, the automatic_payment_source field of the payment request is also required.
The deprecated request_method field of the payment request. Note that invoice objects returned in responses do not include request_method.

string

Select delivery_method

EMAIL Directs Square to send invoices, reminders, and receipts to the customer using email.

description

The description of the invoice, which is displayed on the invoice.

Min Length 1 Max Length 65536

string

invoice_number

A user-friendly invoice number that is displayed on the invoice. The value is unique within a location. If not provided when creating an invoice, Square assigns a value. It increments from 1 and is padded with zeros making it 7 characters long (for example, 0000001 and 0000002).

Min Length 1 Max Length 191

string

location_id

The ID of the location that this invoice is associated with.

If specified in a CreateInvoice request, the value must match the location_id of the associated order.

Min Length 1 Max Length 255

string

order_id

The ID of the order for which the invoice is created. This field is required when creating an invoice, and the order must be in the OPEN state.

To view the line items and other information for the associated order, call the RetrieveOrder endpoint using the order ID.

Min Length 1 Max Length 255

string

payment_conditions

France only. The payment terms and conditions that are displayed on the invoice. For more information, see Payment conditions.

For countries other than France, Square returns an INVALID_REQUEST_ERROR with a BAD_REQUEST code and "Payment conditions are not supported for this location's country" detail if this field is included in CreateInvoice or UpdateInvoice requests.

Min Length 1 Max Length 2000

string

payment_requests[0] InvoicePaymentRequest [ ]

automatic_payment_source

The payment method for an automatic payment.

The default value is NONE.

string

Select automatic_payment_source

NONE An automatic payment is not configured for the payment request.
CARD_ON_FILE Use a card on file as the automatic payment method. On the due date, Square charges the card for the amount of the payment request. For CARD_ON_FILE payments, the invoice delivery method must be EMAIL and card_id must be specified for the payment request before the invoice can be published.
BANK_ON_FILE Use a bank account on file as the automatic payment method. On the due date, Square charges the bank account for the amount of the payment request if the buyer has approved the payment. The buyer receives a request to approve the payment when the invoice is sent or the invoice is updated. This payment method applies only to invoices that sellers create in the Seller Dashboard or other Square product. The bank account is provided by the customer during the payment flow. You cannot set BANK_ON_FILE as a payment method using the Invoices API, but you can change a BANK_ON_FILE payment method to NONE or CARD_ON_FILE. For BANK_ON_FILE payments, the invoice delivery method must be EMAIL.

card_id

The ID of the credit or debit card on file to charge for the payment request. To get the cards on file for a customer, call ListCards and include the customer_id of the invoice recipient.

Min Length 1 Max Length 255

string

due_date

The due date (in the invoice's time zone) for the payment request, in YYYY-MM-DD format. This field is required to create a payment request. If an automatic_payment_source is defined for the request, Square charges the payment source on this date.

After this date, the invoice becomes overdue. For example, a payment due_date of 2021-03-09 with a timezone of America/Los_Angeles becomes overdue at midnight on March 9 in America/Los_Angeles (which equals a UTC timestamp of 2021-03-10T08:00:00Z).

string

fixed_amount_requested_money

If the payment request specifies DEPOSIT or INSTALLMENT as the request_type, this indicates the request amount. You cannot specify this when request_type is BALANCE or when the payment request includes the percentage_requested field.

Money

percentage_requested

Specifies the amount for the payment request in percentage:

When the payment request_type is DEPOSIT, it is the percentage of the order's total amount.
When the payment request_type is INSTALLMENT, it is the percentage of the order's total less the deposit, if requested. The sum of the percentage_requested in all installment payment requests must be equal to 100.

You cannot specify this when the payment request_type is BALANCE or when the payment request specifies the fixed_amount_requested_money field.

string

reminders

A list of one or more reminders to send for the payment request.

InvoicePaymentReminder [ ]

request_type

Identifies the payment request type. This type defines how the payment request amount is determined. This field is required to create a payment request.

string

Select request_type

BALANCE A request for a balance payment. The balance amount is computed as follows: - If the invoice specifies only a balance payment request, the balance amount is the total amount of the associated order. - If the invoice also specifies a deposit request, the balance amount is the amount remaining after the deposit. INSTALLMENT and BALANCE payment requests are not allowed in the same invoice.

tipping_enabled

If set to true, the Square-hosted invoice page (the public_url field of the invoice) provides a place for the customer to pay a tip.

This field is allowed only on the final payment request
and the payment request_type must be BALANCE or INSTALLMENT.

boolean

uid

The Square-generated ID of the payment request in an invoice.

Min Length 1 Max Length 255

string

primary_recipient

The customer who receives the invoice. This customer data is displayed on the invoice and used by Square to deliver the invoice.

This field is required to publish an invoice, and it must specify the customer_id.

InvoiceRecipient

customer_id

The ID of the customer. This is the customer profile ID that you provide when creating a draft invoice.

Min Length 1 Max Length 255

string

sale_or_service_date

The date of the sale or the date that the service is rendered, in YYYY-MM-DD format. This field can be used to specify a past or future date which is displayed on the invoice.

string

scheduled_at

The timestamp when the invoice is scheduled for processing, in RFC 3339 format. After the invoice is published, Square processes the invoice on the specified date, according to the delivery method and payment request settings.

If the field is not set, Square processes the invoice immediately after it is published.

Examples for January 25th, 2020 6:25:34pm Pacific Standard Time:

UTC: 2020-01-26T02:25:34Z

Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00

string

store_payment_method_enabled

Indicates whether to allow a customer to save a credit or debit card as a card on file or a bank transfer as a bank account on file. If true, Square displays a Save my card on file or Save my bank on file checkbox on the invoice payment page. Stored payment information can be used for future automatic payments. The default value is false.

boolean

title

The title of the invoice, which is displayed on the invoice.

Min Length 1 Max Length 255

string

version

The Square-assigned version number, which is incremented each time an update is committed to the invoice.

integer

idempotency_key

A unique string that identifies the CreateInvoice request. If you do not provide idempotency_key (or provide an empty string as the value), the endpoint treats each request as independent.

For more information, see Idempotency.

Max Length 128

string

You are viewing an old version of the API

All Versions

Request

cURL

Ruby

Python

Java

PHP

Node.js

Response

// No response received yet.

Thanks for the feedback. For more help, check out our support resources.

Developer Support Developer Forums

There was an error submitting feedback. Try again later.

Developer Support Developer Forums