Learn how to use the UpdateInvoice endpoint in the Square Invoices API to update invoice settings.
Invoices API

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.

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:

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.

    • You cannot update an invoice in the PAID, REFUNDED, CANCELED, or FAILED terminal states.

    • You cannot update an invoice in the PAYMENT_PENDING state. You must wait for the payment to complete before you can update it. 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.

  • Increments the invoice version.

  • Invokes an invoice.updated webhook event.

The following example UpdateInvoice requests show various update scenarios:

The following UpdateInvoice request updates the title and invoice_number:

Update Invoice
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -X PUT \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0,
      "title": "My Updated Title",
      "invoice_number": "new-number-100"
    }
  }'

If these fields are not 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.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
  • 61
  • 62
  • 63
  • 64
{
  "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",
        "reminders": []
      }
    ],
    "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":"doe@email.com"
    },
    "accepted_payment_methods": {
      "card": true,
      "square_gift_card": false,
      "bank_account": false,
      "buy_now_pay_later": false
    },
    "delivery_method":"EMAIL",
    "custom_fields": []
  },
  "errors": []
}

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
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -X PUT \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0,
      "accepted_payment_methods": {
        "square_gift_card": true
      }
    },
    "fields_to_clear": [
      "payment_requests[a17ee758-fb36-4226-a535-95916example]"
    ]
  }'

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.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
{
  "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",
          "reminders": []
      }
    ],
    "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":"doe@email.com"
    },
    "accepted_payment_methods": {
      "card": true,
      "square_gift_card": true,
      "bank_account": false,
      "buy_now_pay_later": false
    },
    "delivery_method":"EMAIL"",
    "custom_fields": []
  },
  "errors": []
  }
}

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
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -X PUT \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0,
      "payment_requests": [
        {
          "uid": "79e1d50d-6a35-40fc-bfd2-05913example",
          "due_date": "2020-06-15"
        }
      ]
    },
    "fields_to_clear": [
      "payment_requests[a17ee758-fb36-4226-a535-95916example]"
    ]
  }'

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

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
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -X PUT \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0,
      "invoice_number": "new-number-100",
      "payment_requests": [
        {
          "request_type": "DEPOSIT",
          "due_date": "2020-11-30",
          "percentage_requested": "25",
          "automatic_payment_source": "CARD_ON_FILE",
          "card_id": "ccof:I6pHF8bMQghMexample"
        },
        {
          "request_type": "BALANCE",
          "due_date": "2020-12-30",
          "automatic_payment_source": "CARD_ON_FILE",
          "card_id": "ccof:I6pHF8bMQghMexample"
        }
      ]
    },
    "fields_to_clear": [
      "payment_requests[ea89248e-ff10-4958-98e9-2433bexample]"
    ]
  }'

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.

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:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
{
  "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",
        "reminders": []
      },
      {
        "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",
        "reminders": []
      }
    ],
    ...
  }
}

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
  • 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: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0,
      "payment_requests": [
        {
          "uid": "32d69642-1614-4d84-ae4a-75d51example",
          "fixed_amount_requested_money": {
            "amount": 100,
            "currency": "USD"
          }
        }
      ]
    },
    "fields_to_clear": [
      "payment_requests[32d69642-1614-4d84-ae4a-75d51example].percentage_requested"
    ]
  }'

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:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
{
  "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",
        "reminders": []
      },
      {
        "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",
        "reminders": []
      }
    ],
    ...
}

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:

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
  • 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: 2022-11-16' \
  -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:

Update Invoice
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -X PUT \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0
    },
    "fields_to_clear": [
      "custom_fields"
    ]
  }'

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.