Updates an invoice by modifying fields, clearing fields, or both.
Open in API Reference
The ID of the invoice to update.
A string that contains no characters. In an API request this value will appear as ''. Can be used to remove a field’s value.
''
The invoice fields to update. The current invoice version must be specified in the version field. For more information, see Update an invoice.
version
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.
true
A nonexistent value. In an API request this value will appear as null. Can be used to clear a field entirely.
null
The label or title of the custom field. This field is required for a custom field.
The location of the custom field on the invoice. This field is required for a custom field.
The text of the custom field. If omitted, only the label is rendered.
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.
scheduled_at
EMAIL
One of the following is required when creating an invoice:
delivery_method
automatic_payment_source
request_method
invoice
The description of the invoice, which is displayed on the invoice.
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).
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.
CreateInvoice
location_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.
OPEN
To view the line items and other information for the associated order, call the RetrieveOrder endpoint using the order ID.
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.
INVALID_REQUEST_ERROR
BAD_REQUEST
UpdateInvoice
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:
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.
INSTALLMENT
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.
customer_id
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.
YYYY-MM-DD
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
The title of the invoice, which is displayed on the invoice.
The Square-assigned version number, which is incremented each time an update is committed to the invoice.
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.
idempotency_key
For more information, see Idempotency.
// No response received yet.