API Explorer

You are viewing an old version of the API

All Versions

Update invoice

PUT /v2/invoices/{invoice_id}

Updates an invoice by modifying fields, clearing fields, or both.

Open in API Reference

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

Parameters

invoice_id

The ID of the invoice to update.

string

Body

invoice

The invoice fields to update. The current invoice version must be specified in the version field. For more information, see Update an invoice.

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

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

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.
SHARE_MANUALLY Directs Square to take no action on the invoice. In this case, the seller or application developer follows up with the customer for payment. For example, a seller might collect a payment in the Seller Dashboard or Point of Sale POS application. The seller might also share the URL of the Square-hosted invoice page public_url with the customer to request payment.
SMS Directs Square to send invoices and receipts to the customer using SMS text message. You cannot set SMS as a delivery method using the Invoices API, but you can change an SMS delivery method to EMAIL or SHARE_MANUALLY.

description

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

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

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.

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.

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.

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

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.

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.

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.

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

DEPOSIT A request for a deposit payment. You have the option of specifying an exact amount or a percentage of the total order amount. If you request a deposit, it must be due before any other payment requests.

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.

string

payment_requests[1] InvoicePaymentRequest [ ]

automatic_payment_source

The payment method for an automatic payment.

The default value is NONE.

string

Select automatic_payment_source

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.

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.

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.

string

fixed_amount_requested_money

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.

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

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

title

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

string

version

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

integer

fields_to_clear

The list of fields to clear. For examples, see Update an invoice.

string[]

idempotency_key

A unique string that identifies the UpdateInvoice 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.

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