Update Invoices

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.

Update an invoice

To update an invoice, call UpdateInvoice and provide the following information:

The ID of the invoice to update.
An Invoice object that specifies the current version of the invoice and contains any new fields or existing fields with updated values.
If you need to get the ID and version, call SearchInvoices or ListInvoices. If you have the ID but need the version, call GetInvoice.
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:

curl https://connect.squareupsandbox.com/v2/invoices/{{INVOICE_ID}} \
  -X PUT \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoice": {                                       // required  
      "version": 0,                                    // required  
       // include new fields or existing fields with updated values
    },
    "fields_to_clear": [                               // optional  
       // include existing fields whose values you want to clear
    ]
  }'

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.
You cannot update the primary_recipient field. For more information, see Limitations with the Customers API integration.
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 doesn't notify the customer.
Increments the invoice version.
Invokes an invoice.updated webhook event.

Link to section

Example requests

The following example UpdateInvoice requests show various update scenarios:

Link to section

Example 1: Update an invoice number and title

The following UpdateInvoice request updates the title and invoice_number:

Update invoice

If these fields aren't 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.

{
  "invoice":{
    "id":"inv:0-ChD_YDNHr4E6FJCeveEoAexample",
    "version":0,
    "location_id":"S8GWD5example",
    "order_id":"81b7Ar7KPHmlXHs2qhjMc5example",
    "payment_requests":[
      {
        "uid":"a17ee758-fb36-4226-a535-95916example",
        "request_type":"DEPOSIT",
        "due_date":"2020-06-15",
        "tipping_enabled": false,
        "percentage_requested":"20",
        "card_id":"ccof:aD1D4q9aUXTkexample",
        "computed_amount_money":{
           "amount":100,
           "currency":"USD"
        },
        "total_completed_amount_money":{
           "amount":0,
           "currency":"USD"
        },
        "automatic_payment_source":"CARD_ON_FILE"
      },
      {
        "uid":"79e1d50d-6a35-40fc-bfd2-05913example",
        "request_type":"BALANCE",
        "due_date":"2020-07-01",
        "tipping_enabled": true,
        "card_id":"ccof:aD1D4q9aUXTkexample",
        "computed_amount_money":{
          "amount":400,
          "currency":"USD"
        },
        "total_completed_amount_money":{
          "amount":0,
          "currency":"USD"
        },
        "automatic_payment_source":"CARD_ON_FILE"
      }
    ],
    "invoice_number":"000034",
    "status":"DRAFT",
    "timezone":"Etc/UTC",
    "created_at":"2020-06-10T18:49:06Z",
    "updated_at":"2020-06-10T18:49:06Z",
    "primary_recipient":{
      "customer_id":"DJREAYPRBMSSFAB4TGAexample",
      "given_name":"John",
      "family_name":"Doe",
      "email_address":"[email protected]"
    },
    "accepted_payment_methods": {
      "card": true,
      "square_gift_card": false,
      "bank_account": false,
      "buy_now_pay_later": false,
      "cash_app_pay": false
    },
    "delivery_method":"EMAIL"
  }
}

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.

Update invoice

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.

{
  "invoice":{
    "id":"inv:0-ChD_YDNHr4E6FJCeveEoAexample",
    "version":1,
    "location_id":"S8GWD5example",
    "order_id":"81b7Ar7KPHmlXHs2qhjMc5example",
    "payment_requests":[
      {
        "uid":"79e1d50d-6a35-40fc-bfd2-05913example",
        "request_type":"BALANCE",
        "due_date":"2020-07-01",
        "tipping_enabled": true,
        "card_id":"ccof:aD1D4q9aUXTkexample",
        "computed_amount_money":{
          "amount":500,
          "currency":"USD"
        },
        "total_completed_amount_money":{
          "amount":0,
          "currency":"USD"
        },
          "automatic_payment_source":"CARD_ON_FILE"
      }
    ],
    "invoice_number":"000034",
    "status":"DRAFT",
    "timezone":"Etc/UTC",
    "created_at":"2020-06-10T18:49:06Z",
    "updated_at":"2020-06-10T20:28:50Z",
    "primary_recipient":{
      "customer_id":"DJREAYPRBMSSFAB4TGexample",
      "given_name":"John",
      "family_name":"Doe",
      "email_address":"[email protected]"
    },
    "accepted_payment_methods": {
      "card": true,
      "square_gift_card": true,
      "bank_account": false,
      "buy_now_pay_later": false,
      "cash_app_pay": false
    },
    "delivery_method":"EMAIL"
  }
}

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.

Update invoice

Link to section

Example 3: Remove and add payment requests

The following UpdateInvoice request removes an existing payment request and adds two new payment requests:

Update invoice

Note the following:

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:

{
  "invoice": {
    "id": "inv:0-ChB8ZZei5_Hn7WiK8tGL0example",
    "version": 0,
    "location_id": "S8GWD5example",
    "order_id": "8tXvK5qwjkEPbeLixWaKSxexample",
    "payment_requests": [
      {
        "uid": "32d69642-1614-4d84-ae4a-75d51example",
        "request_type": "DEPOSIT",
        "due_date": "2020-06-22",
        "tipping_enabled": false,
        "percentage_requested": "20",
        "computed_amount_money": {
          "amount": 100,
          "currency": "USD"
        },
        "total_completed_amount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "automatic_payment_source": "NONE"
      },
      {
        "uid": "622a0315-e640-4a7a-9763-87461example",
        "request_type": "BALANCE",
        "due_date": "2020-09-01",
        "tipping_enabled": false,
        "computed_amount_money": {
          "amount": 400,
          "currency": "USD"
        },
        "total_completed_amount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "automatic_payment_source": "NONE"
      }
    ],
    ...
  }
}

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:

Update invoice

Both invoice and fields_to_clear specify the same uid value. As a result, the specified update is applied to the same payment request:

invoice adds the fixed_amount_requested_money field.
fields_to_clear removes the percentage_requested field.

The updated invoice is shown:

{
  "invoice": {
    "id": "inv:0-ChB8ZZei5_Hn7WiK8tGL0example",
    "version": 1,
    "location_id": "S8GWD5example",
    "order_id": "8tXvK5qwjkEPbeLixWaKSxexample",
    "payment_requests": [
      {
        "uid": "32d69642-1614-4d84-ae4a-75d51example",
        "request_type": "DEPOSIT",
        "due_date": "2020-06-22",
        "tipping_enabled": false,
        "fixed_amount_requested_money": {
          "amount": 100,
          "currency": "USD"
        },
        "computed_amount_money": {
          "amount": 100,
          "currency": "USD"
        },
        "total_completed_amount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "automatic_payment_source": "NONE"
      },
      {
        "uid": "622a0315-e640-4a7a-9763-87461example",
        "request_type": "BALANCE",
        "due_date": "2020-09-01",
        "tipping_enabled": false,
        "computed_amount_money": {
          "amount": 400,
          "currency": "USD"
        },
        "total_completed_amount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "automatic_payment_source": "NONE"
      }
    ],
    ...
}

Link to section

Example 5: Update custom fields

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:

...
"custom_fields": [
  {
    "label": "Rules",
    "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"
  }
]
...

Note

Custom fields are supported only with an Invoices Plus subscription.

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

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:

Update invoice

Link to section

Docs

Update Invoices

On this page

Update an invoice

Note

Example requests

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

Note

See also

On this page