Update Invoices

Learn how to add, change, or clear fields in an invoice using the Invoices API.

Overview

Applications can call the UpdateInvoice endpoint in the Invoices API to update an invoice. For example, you can add or update the title, change the payment schedule, and change accepted payment methods. This endpoint supports sparse updates.

Link to section

Requirements and limitations

Only invoices in the DRAFT, SCHEDULED, UNPAID, or PARTIALLY_PAID state 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.
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 in the SCHEDULED, UNPAID, or PARTIALLY_PAID state:
- 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.
UpdateInvoice cannot be used to upload or delete an invoice attachment. To manage attachments, use the CreateInvoiceAttachment or DeleteInvoiceAttachment endpoint. For more information, see Create or Delete Invoice Attachments.

Link to section

Update an invoice

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

The ID of the invoice to update.
An invoice object with:
- The current version of the invoice.
- Any new fields to add and existing fields to change or clear (remove).
  - To change fields, provide the updated values.
  - To clear fields, specify a null value.
    Updating payment_requests or reminders uses a different syntax. To change a value, specify the uid and provide the updated value. To clear an element, specify the uid and include the remove field set to true.
    The Invoices API also supports using the fields_to_clear field to clear fields. However, using null values or the remove field is the recommended field clearing method.
An optional idempotency_key to ensure idempotency.

Note

If you need to get the invoice ID and version, call SearchInvoices or ListInvoices. If you have the ID but need the version, call GetInvoice.

The following UpdateInvoice request adds (or updates) the invoice_number field and clears the description field.

In the Invoice object:

Specify a value for invoice_number.
Set the description value to null.

Update invoice

For this example, Square adds the invoice_number field if isn't already defined for the invoice; otherwise, Square updates its value.

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.
Opting out of sending EMAIL or SMS notifications to customers isn't possible when updating an invoice with the Invoices API.
Increments the invoice version.
Triggers an invoice.updated webhook event.

Link to section

Additional examples

The following example UpdateInvoice requests show various update scenarios:

Link to section

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-EXAMPLE",
        "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-EXAMPLE",
        "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.

In the Invoice.payment_requests array, specify the uid of the payment request you want to remove and set the remove field to true.

Update invoice

To remove a reminder in the payment request with the remove field, use this format:

  ...
  "payment_requests": [
    {
      "uid": "a17ee758-fb36-4226-a535-EXAMPLE",
      "reminders": [
        { 
          "uid": "ba4ae57d-f283-4b2e-a0d0-EXAMPLE",
          "remove": true      
        }
      ]
    }
  ]
  ...

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-EXAMPLE",
        "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"
  }
}

Link to section

Example variation: Remove the deposit request and change the balance due date

Now consider the following variation that removes one payment request and updates another. For example, suppose you want to remove the deposit payment request in the preceding invoice and change the due date of the remaining balance payment request.

In the Invoice.payment_requests array:

Specify the uid of the payment request to update with the new value for the due_date field.
Specify the uid of the payment request to remove with the remove field set to true.

Update invoice

Link to section

Remove and add payment requests

The following UpdateInvoice request removes an existing payment request and adds two payment requests. This scenario might apply if you want to collect a deposit instead of requesting one payment in full.

In the update request, specifying the uid of an invoice payment request indicates that you want to update an existing payment request. If the uid field is omitted, Square attempts to add a new payment request.

In the Invoice.payment_requests array:

Define the new payment requests.
Specify the uid of the payment request to remove with the remove field set to true.

Update invoice

Link to section

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-EXAMPLE",
        "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-EXAMPLE",
        "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. To make this change, the following UpdateInvoice request performs two distinct updates to the same payment request:

Add a new fixed_amount_requested_money field.
Remove the percentage_requested field.

In the Invoice.payment_requests array:

Specify uid and define the new fixed_amount_requested_money.
Set the percentage_requested value to null.

Update invoice

The following is the updated invoice:

{
  "invoice": {
    "id": "inv:0-ChB8ZZei5_Hn7WiK8tGL0EXAMPLE",
    "version": 1,
    "location_id": "S8GWD5EXAMPLE",
    "order_id": "8tXvK5qwjkEPbeLixWaKSxEXAMPLE",
    "payment_requests": [
      {
        "uid": "32d69642-1614-4d84-ae4a-EXAMPLE",
        "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-EXAMPLE",
        "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

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.

You can also remove all custom fields from the invoice:

In the Invoice object, set the custom_fields value to null.

Update invoice

Link to section

Docs

Update Invoices

On this page

Overview

Requirements and limitations

Update an invoice

Note

Additional examples

Update payment requests by removing the deposit request

Example variation: Remove the deposit request and change the balance due date

Remove and add payment requests

Replace payment request percentages with exact amounts

Update custom fields

Note

See also

On this page