Cancel or Delete Invoices

Applies to: Invoices APIInvoices API

Learn how to use Invoices API endpoints to cancel a published invoice or delete a draft invoice.

To cancel a published invoice, call CancelInvoiceCancelInvoice 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 SearchInvoicesSearchInvoices or ListInvoicesListInvoices. If you have the ID but need the version, call GetInvoiceGetInvoice.

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.
• Updates the associated order based on the invoice status:

  • SCHEDULED or UNPAID invoices - Sets the order state to CANCELED and sets the state of any open fulfillments on the order to CANCELED.

  • PARTIALLY_PAID invoices - Sets the order state to COMPLETED and replaces existing line items with a new CUSTOM_AMOUNT line item totaling the partially paid amount.

    Square doesn't automatically refund any payment amount.

• 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 invoice.updated and invoice.canceled webhook eventswebhook events. order.updated events are also invoked after Square updates the associated order.

You cannot cancel invoices in the DRAFT state or in the PAID, REFUNDED, CANCELED, or FAILED terminal state. Note that you can deletedelete a DRAFT invoice.

Invoices aren't automatically updated or canceled if the customer profile assigned as the invoice recipient is deleted from the Customer Directory. If the invoice has remaining scheduled payments, Square continues to send the invoice to the primary_recipient.email address. Any remaining automatic payments fail, but the customer can still pay the invoice from the Square-hosted invoice payment page.

Consider canceling these invoices if there isn't a valid reason to keep them. You can subscribe to the customer.deletedcustomer.deleted webhook event to be notified when customers are deleted.

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

• The ID of the invoice to delete. The invoice must be in the DRAFT state.
• The current version of the invoice. You can optionally provide this in the version query parameter to enable optimistic concurrency controloptimistic concurrency control.

If you need to get the ID and version, call SearchInvoicesSearchInvoices or ListInvoicesListInvoices. If you have the ID but need the version, call GetInvoiceGetInvoice.

After an invoice is deleted, Square does the following:

• Removes the invoice from the seller account. Deleted invoices aren't returned by GetInvoice, ListInvoices, or SearchInvoices requests.
• Permanently deletes any attachmentsattachments.
• Changes the state of the associated order to CANCELED.
• Invokes an invoice.deleted webhook eventwebhook event. The order.updated event is also invoked after Square sets the associated order to the CANCELED state.

• Invoices APIInvoices API
• API Reference: Invoices APIAPI Reference: Invoices API