Skip to main content
POST
Cancel order (partners)
Cancels an order you injected, looking it up by the external id you gave it. Unlike the backoffice endpoint, you do not need to store our internal UUID.
This endpoint runs the cancellation policy: Fire’s rules plus whatever the account configured. Before trying, you can ask Cancellation eligibility, which returns the same verdict and the same code with a 200 and no side effects.

The order of the steps depends on the fiscal gateway

This is the part integrations get wrong most often, and the only place where the order matters.
Fire numbers the receipt, so the fiscal void comes first:
1

Void the receipt

POST /api/v2/external/fiscal/numbering with operation: "CANCEL". It returns the credit note. See Fiscal numbering v2.
2

Cancel the order

Only now, this endpoint.
It is the same pattern as issuing — the fiscal fact first, the order second — which makes it easy to remember: you void the way you issue.If you invert the steps, this endpoint answers 409 with FISCAL_REPRESENTATION_NOT_VOIDED. It is not transient: retrying will not fix it.
Fire works out which of the two cases applies on its own, from that account, country and vendor’s configuration. You do not have to find out: if the credit note applies to you, the 409 tells you.
string
required
Bearer <api-key> with the orders:write scope, vendor-scoped.
string
default:"es"
Language of the rejection reason: es, en or pt. It is the same parameter already used by Cancellation eligibility and Fiscal numbering.It goes in the URL:
It only affects Fire’s own rules, which carry labels in all three languages. The text of a rule configured by the account comes back exactly as the account wrote it, in whatever language that is. Without this parameter, Spanish.
string
required
The order’s external id — the same orderId you sent when injecting it. Not our internal UUID: you do not need to store it.
string
required
The reason. Between 5 and 500 characters. With a catalog, the text of the chosen reason.
string
The reason id within the catalog. For aggregator channels it must come from the SAG catalog.
string
Free-form note, up to 500 characters. Stored separately from the reason.
string
The group. You do not need to send it: the backend derives it.

What a rejection carries

Beyond the code, a 409 body carries the reason ready to display:
string
The headline: the name of the rule that denied. This is what fits in a short notice.
string
The long why. Only present when the rule has one. It travels apart from message so you can show just the headline when there is no room for more.
The number behind the rejection, when the rule compares one: the limit and the actual value. Lets you say “17 minutes past” without parsing the text.
object
What it decided with. A receipt for diagnosing, not for showing to a person.

Rejection codes

All of them come back as 409. Branch on code, never on the message: the text is for a person to read and may change or be translated without notice.
A 200 means the order was cancelled. It does not mean the fiscal document is already voided: with a gateway you did that in the previous step, and with native issuing it settles later, through the provider’s callback.