Use the 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.
A fields_to_clear array 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.
An optional idempotency_key used to ensure idempotency.
The following excerpt shows the type of changes that you can provide in the invoice and fields_to_clear fields:
Note
When updating custom fields, you must provide the complete custom_fields array. For more information, see the Update custom fields example.
The following restrictions apply to updating an invoice in a DRAFT state:
You cannot update the order_id or location_id field.
Updating the primary_recipient contact 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 order_id or location_id field.
After publishing, only invoices in the SCHEDULED, UNPAID, or PARTIALLY_PAID states can be updated. You cannot update invoices in the PAID, REFUNDED, PARTIALLY_REFUNDED, CANCELED, or FAILED terminal state.
For invoices in the PAYMENT_PENDING state, you must wait for the payment to complete before you can update it (assuming it reaches the PARTIALLY_PAID state). 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_method setting for the invoice:
EMAIL. Square sends an email to the customer.
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 does not notify the customer.
If these fields are not previously set, the update operation adds them to the invoice.
Link to section
Example 2: Update payment requests by removing the deposit request
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.
The following 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:
A payment_requests field in the invoice object that specifies the uid of the payment request to update, along with the new value for the due_date field.
The fields_to_clear field that specifies the uid of the payment request to remove.
fields_to_clear identifies the specific payment request to remove by providing its uid value.
invoice specifies payment_requests without referring to any existing uid value. Therefore, the Invoices API adds these payment requests. If you added a uid value to any of these payment requests, it would indicate that you wanted to update the values of an existing payment request.
Link to section
Example 4: Replace payment request percentages with exact amounts
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 fixed_amount_requested_money field.
Remove the percentage_requested field.
The following UpdateInvoice request performs both of these updates:
Unlike other invoice fields, the Invoices API does not 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:
Update Invoice
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
curl https://connect.squareupsandbox.com/v2/invoices/{{INVOICE_ID}} \
-X PUT \
-H 'Square-Version: 2023-05-17' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
"idempotency_key": "{UNIQUE_KEY}",
"invoice": {
"version": 0,
"custom_fields": [
{
"label": "Terms and Conditions",
"value": "You must agree to the following terms and conditions ...",
"placement": "ABOVE_LINE_ITEMS"
},
{
"label": "Refund Policy",
"value": "Refunds will be made on the original payment method ...",
"placement": "ABOVE_LINE_ITEMS"
}
]
}
}'
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: