Use the CancelInvoice
endpoint in the Invoices API to cancel a published invoice or the DeleteInvoice
endpoint to delete a draft 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
, orPARTIALLY_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:
Cancel invoice
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 toCANCELED
. Canceled invoices remain accessible in the seller account and are returned byGetInvoice
,ListInvoices
, andSearchInvoices
requests. - Sets the
state
of the associated order toCANCELED
. - 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 doesn't notify the customer. - Invokes an
invoice.canceled
webhook event. Theorder.updated
event is also invoked after Square sets the associated order to theCANCELED
state.
- For
You cannot cancel invoices in the DRAFT
state or in the PAID
, REFUNDED
, CANCELED
, or FAILED
terminal state.
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:
Delete invoice
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 aren't returned by
GetInvoice
,ListInvoices
, orSearchInvoices
requests. - Changes the
state
of the associated order toCANCELED
. - Invokes an
invoice.deleted
webhook event. Theorder.updated
event is also invoked after Square sets the associated order to theCANCELED
state.