UpdateInvoice endpoint in the Invoices API to update a draft or published invoice. You can add fields and change or clear the values of invoice fields.
To update an invoice, call UpdateInvoice and provide the following information:
The ID of the invoice to update.
Invoiceobject that specifies the current
versionof the invoice and contains any new fields or existing fields with updated values.
fields_to_cleararray with a comma-separated list of fields to clear. Only include this field in the request when you want to clear (remove) fields from the invoice.
idempotency_keyused to ensure idempotency.
The following excerpt shows the type of changes that you can provide in the
The following restrictions apply to updating an invoice in a
- You cannot update the
- Updating the
primary_recipientcontact information requires two update requests. Use the first request to clear this field and the second request to add the field again.
The following restrictions apply to updating a published invoice:
You cannot update the
You cannot update the
primary_recipientfield. For more information, see Limitations with the Customers API integration.
After publishing, only invoices in the
PARTIALLY_PAIDstates can be updated. You cannot update invoices in the
For invoices in the
PAYMENT_PENDINGstate, you must wait for the payment to complete before you can update it (assuming it reaches the
PARTIALLY_PAIDstate). In addition, the seller or customer cannot initiate another payment for an invoice in this state.
After an invoice is updated, Square does the following:
Notifies the seller, if the Updated notification is enabled in the seller's notification settings.
Notifies the customer, as determined by the
delivery_methodsetting for the invoice:
SMS- Square sends a text message to the customer unless the customer has opted out of text message updates from Square invoices.
SHARE_MANUALLY- Square doesn't notify the customer.
Opting out of sending
SMSnotifications to customers is not possible when updating an invoice with the Invoices API.
Increments the invoice version.
The following example
UpdateInvoice requests show various update scenarios:
- Example 1: Update an invoice number and title
- Example 2: Update payment requests by removing the deposit request
- Example 3: Remove and add payment requests
- Example 4: Replace payment request percentages with exact amounts
- Example 5: Update custom fields
UpdateInvoice request updates the
If these fields aren't previously set, the update operation adds them to the invoice.
Consider the following draft invoice that requests a deposit payment and a balance payment due at a later date. The invoice is configured to automatically charge a card on file and to accept credit and debit card payments on the Square-hosted invoice payment page.
UpdateInvoice request removes the deposit payment request from the preceding invoice and allows customers to use a Square gift card to make a payment on the invoice payment page. Note the
fields_to_clear field, which specifies
payment_requests[a17ee758-fb36-4226-a535-95916example] as the field to remove. The
uid index value for
payment_requests identifies the specific payment request to remove.
The following is the updated draft invoice. It now requests only one automatic payment in full (no deposit) and accepts credit card, debit card, and Square gift card payments on the invoice payment page.
Example variation: Remove the deposit request and change the balance due date
Now consider the following variation. Suppose you want to remove the deposit payment request and change the due date of the remaining balance payment request. In other words, you want to remove one payment request and update another.
In this case, the
UpdateInvoice request body must include:
payment_requestsfield in the
invoiceobject that specifies the
uidof the payment request to update, along with the new value for the
fields_to_clearfield that specifies the
uidof the payment request to remove.
UpdateInvoice request removes an existing payment request and adds two new payment requests:
Note the following:
fields_to_clearidentifies the specific payment request to remove by providing its
payment_requestswithout referring to any existing
uidvalue. Therefore, the Invoices API adds these payment requests. If you added a
uidvalue to any of these payment requests, it would indicate that you wanted to update the values of an existing payment request.
Consider the following draft invoice that has two payment requests: a deposit of 20% and the remaining balance due at a later date. The following is an excerpt of the invoice:
Now suppose you want to specify the exact amount for these payment requests instead of percentages. These are two distinct updates to the same payment request:
- Add a new
- Remove the
UpdateInvoice request performs both of these updates:
fields_to_clear specify the same
uid value. As a result, the specified update is applied to the same payment request:
The updated invoice is shown:
Unlike other invoice fields, the Invoices API doesn't support using sparse updates to add or change custom fields. To make these changes, you must provide the complete
custom_fields list in the update request. For example, consider an invoice that includes the following custom fields:
If you want to change the label from "Rules" to "Terms and Conditions", the
invoice object in the request must include complete definitions for both custom fields. For example:
Omitting a custom field object or field from the request removes the object or field, or returns an error if the field is required. However, you can use the
fields_to_clear field if you want to remove all custom fields from the invoice. For example: