Cancel or Delete Invoices

Use the CancelInvoice endpoint in the Invoices API to cancel a published invoice or the DeleteInvoice endpoint to delete a draft invoice.

Link to section

Cancel an invoice

To cancel a published invoice, call CancelInvoice and provide the following information:

• The ID of the invoice to cancel. The invoice must be in the SCHEDULED, UNPAID, or PARTIALLY_PAID state.

• The current version of the invoice.

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

The following is an example request:

curl https://connect.squareupsandbox.com/v2/invoices/{{INVOICE_ID}}/cancel \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": 1
  }'

The canceled invoice is returned in the response, as shown in the following excerpt:

{
  "invoice": {
    "id": "gt2zv1z6mnUm1V7example",
    "version": 2,
    "location_id": "S8GWD5example",
    "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
    ...
    "status": "CANCELED",
    ...
  }
}

After an invoice is canceled, Square does the following:

• Sets the status of the invoice to CANCELED. Canceled invoices remain accessible in the seller account and are returned by GetInvoice, ListInvoices, and SearchInvoices requests.

• Sets the state of the associated order to CANCELED.

• Stops any automatic scheduled actions, such as sending reminders or charging a card on file. Sellers can no longer collect payments from a canceled invoice.

• Notifies the seller, if the Canceled notification is enabled in the seller's notification settings.

• Notifies the customer, as determined by the delivery_method setting for the invoice:

  • For EMAIL, Square sends an email notification.

  • For SMS, Square sends a text message.

  • For SHARE_MANUALLY, Square does not notify the customer.

  • Invokes an invoice.canceled webhook event. The order.updated event is also invoked after Square sets the associated order to the CANCELED state.

You cannot cancel invoices in the DRAFT state or in the PAID, REFUNDED, CANCELED, or FAILED terminal state.

Link to section

Delete an invoice

To delete an invoice, call DeleteInvoice and provide the following information:

• The ID of the invoice to delete. The invoice must be in the DRAFT state. If you need to get the ID, call SearchInvoices or ListInvoices.

The following is an example request:

curl https://connect.squareupsandbox.com/v2/invoices/{{INVOICE_ID}} \
  -X DELETE \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an example of a successful response:

{}

If the request fails, Square returns error information in the errors field.

{
  "errors": [
    {
      "code": "BAD_REQUEST",
      "detail": "Only DRAFT invoices can be deleted",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}

After an invoice is deleted, Square does the following:

• Removes the invoice from the seller account. Deleted invoices are not returned by GetInvoice, ListInvoices, or SearchInvoices requests.

• Changes the state of the associated order to CANCELED.

• Invokes an invoice.deleted webhook event. The order.updated event is also invoked after Square sets the associated order to the CANCELED state.

Link to section

Related topics

• Invoices API Overview

• API Reference: Invoices