PUT /v2/invoices/{invoice_id}

The ID of the invoice to update.

Default value: "application/json"

Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see Manage Invoices Using the Invoices API.

The description of the invoice. This is visible to the customer receiving the invoice.

The URL of the Square-hosted invoice page. After you publish the invoice using the PublishInvoice endpoint, Square hosts the invoice page and returns the page URL in the response.

The status of the invoice.

The timestamp when the invoice was last updated, in RFC 3339 format.

The Square-assigned ID of the invoice.

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.

The time zone used to interpret calendar dates on the invoice, such as due_date. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.

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

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.

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

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.

Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.

The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

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

The title of the invoice.

The payment schedule for the invoice, represented by one or more payment requests that define payment settings, such as amount due and due date. An invoice supports the following payment request combinations:

• One balance
• One deposit with one balance
• 2–12 installments
• One deposit with 2–12 installments

This field is required when creating an invoice. It must contain at least one payment request. All payment requests for the invoice must equal the total order amount. For more information, see Payment requests.

Adding INSTALLMENT payment requests to an invoice requires an Invoices Plus subscription.

Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.

The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

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

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.

Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.

The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

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

The payment method for an automatic payment.

The default value is NONE.

Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.

The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

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.

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

A Square-assigned ID that uniquely identifies the reminder within the InvoicePaymentRequest.

If sent, the timestamp when the reminder was sent, in RFC 3339 format.

The reminder message.

The status of the reminder.

The number of days before (a negative number) or after (a positive number) the payment request due_date when the reminder is sent. For example, -3 indicates that the reminder should be sent 3 days before the payment request due_date.

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.

Indicates how Square processes the payment request. DEPRECATED at version 2021-01-21. Replaced by the Invoice.delivery_method and InvoicePaymentRequest.automatic_payment_source fields.

One of the following is required when creating an invoice:

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

Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.

The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

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

The payment methods that customers can use to pay an invoice on the Square-hosted invoice page.

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

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

This option is allowed only for invoices that have a single payment request of type BALANCE.

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

The timestamp when the invoice was created, in RFC 3339 format.

Additional seller-defined fields to render on the invoice. These fields are visible to sellers and buyers on the Square-hosted invoice page and in emailed or PDF copies of invoices. For more information, see Custom fields.

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

Max: 2 custom fields

The location of the custom field on the invoice. This field is required for a custom field.

The label or title of the custom field. This field is required for a custom field.

The text of the custom field. If omitted, only the label is rendered.

Provides customer data that Square uses to deliver an invoice.

The recipient's family (that is, last) name.

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

The recipient's given (that is, first) name.

The recipient's email address.

The name of the recipient's company.

Represents a postal address in a country. The address format is based on an open-source library from Google. For more information, see AddressValidationMetadata. This format has dedicated fields for four address components: postal code, locality (city), administrative district (state, prefecture, or province), and sublocality (town or village). These components have dedicated fields in the Address object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons.

For the remaining address components, the Address type provides the address_line_1 and address_line_2 fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want.

Note that, in the current implementation, all other Address type fields are blank. These include address_line_3, sublocality_2, sublocality_3, administrative_district_level_2, administrative_district_level_3, first_name, last_name, and organization.

When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.

The third line of the address, if any.

Optional first name when it's representing recipient.

The address's postal code.

Optional organization name when it's representing recipient.

The second line of the address, if any.

The first line of the address.

Fields that start with address_line provide the address's most specific details, like street number, street name, and building name. They do not provide less specific details like city, state/province, or country (these details are provided in other fields).

A civil entity within the address's administrative_district_level_2, if any.

A civil region within the address's sublocality, if any.

A civil entity within the address's administrative_district_level_1. In the US, this is the county.

The city or town of the address.

A civil region within the address's locality, if any.

Optional last name when it's representing recipient.

A civil entity within the address's country. In the US, this is the state.

A civil region within the address's sublocality_2, if any.

The address's country, in ISO 3166-1-alpha-2 format.

The recipient's phone number.

The ID of the subscription associated with the invoice. This field is present only on subscription billing invoices.

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

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.