order.cancelled

v3 · current
v2.2 · deprecated
v1 · deprecated
v0 · deprecated

You are reading the current (v3) contract for order.cancelled. v3 is a breaking change in the fiscal context only: cancellation.metadata.fiscal becomes cancellation.fiscal, structured as { status, authority }, and it now applies to every country with an authorized document, not only Brazil. cancellation.metadata is no longer emitted. The rest of the event is unchanged. See Path changes from the previous version.

The v2.2 contract is deprecated — kept as a historical reference. Open it here: order.cancelled — v2.2.

order.cancelled fires when a previously injected order is cancelled — from the Fire backoffice (cancellationSource: backoffice), or through an adapter or the cancellation API (cancellationSource: adapter). It does not retract a prior order.completed for the same order; both events are emitted independently.

This event does not mean the fiscal document is annulled. It is emitted when the order is cancelled, before the authority is asked. When the order had an authorized document, cancellation.fiscal describes that document as it was at that moment — still SALE_INVOICE, with cancelledAt: null. The authority’s confirmation arrives later in order.reversed.

Trigger condition

Fire emits order.cancelled once when an order transitions to CANCELLED, regardless of its previous payment state, with full audit context.


Coverage	Global — every country, every channel
Idempotency key	`event.id`
Fires more than once	Once per active Integration Flow subscribed to the event; retried on delivery failure
Ordering	Not guaranteed against `order.completed` — sort by timestamps if you need it
Fiscal context	`cancellation.fiscal` when the order had an authorized document

What’s in `trigger.data`

The same V4 order snapshot as order.completed, with four differences:

status is "CANCELLED".
paymentStatus is unchanged (typically "SUCCEEDED" if the order had been paid).
A top-level cancellation block carries the audit metadata and, when applicable, the fiscal document.
There is no top-level data.fiscal. On this event the authority’s document lives only in cancellation.fiscal.

policy and lastKnown travel exactly as on order.completed. fiscalRepresentation has the same shape, but when a credit note was numbered for the cancellation it carries that note on top and the invoice in history. In Brazil (PlugNotas) fiscalRepresentation is null: there is no numbering step. authority.providerIdentity and authority.providerMetadata appear on documents stored under this contract; on earlier orders the keys may be missing — treat a missing key like null.

Example — Brazil, with an authorized document (sanitized)

{
  "event": { "id": "…", "type": "order.cancelled", "createdAt": "2026-09-15T05:06:45.562Z" },
  "data": {
    "orderId": "15801bd1-83d3-4d70-bb1b-793fd30b7bec",
    "orderCode": "OC-br-001",
    "status": "CANCELLED",
    "paymentStatus": "SUCCEEDED",
    "store": { /* same as order.completed */ },
    "orderLines": [ /* same as order.completed */ ],
    "policy": { "deferredPayment": { "eligible": false, "resolvedAt": "2026-09-15T05:00:45.760Z", "configVersion": "fnv1a:a0c02d27", "resolvedFrom": { "channelCode": "KIOSK", "fulfillmentCode": "DINE-IN", "paymentMethod": null } } },
    "lastKnown": { "kds": { "status": "preparing", "sourceEvent": "order.status_updated" }, "fiscal": { "status": "authorized", "sourceEvent": "order.invoiced" } },
    "fiscalRepresentation": null,

    "cancellation": {
      "cancellationId": "6fcb0a30-cfde-4ffe-96ef-545dde3fa87c",
      "cancelledAt": "2026-09-15T05:06:44.359Z",
      "cancelledBy": "4fadc5f3-d9da-4756-978d-5a8cffc25d40",
      "cancellationType": "OTHER",
      "cancellationGroup": "Other",
      "cancellationReason": "Customer requested cancellation",
      "cancellationNote": null,
      "cancellationSource": "backoffice",

      "fiscal": {
        "status": "authorized",
        "authority": {
          "documentType": "SALE_INVOICE",
          "docSubtype": "nfce",
          "documentNumber": "12388",
          "issuedAt": "2026-09-15T05:00:48.003Z",
          "authorizedAt": "2026-09-15T03:00:00.000Z",
          "cancelledAt": null,
          "authorizationMode": "ONLINE",
          "providerDocId": "6aa8d10117b687522d90ae0a",
          "pdfUrl": "https://api.fiscal-provider.example/nfce/6aa8d10117b687522d90ae0a/pdf",
          "xmlUrl": "https://api.fiscal-provider.example/nfce/6aa8d10117b687522d90ae0a/xml",
          "amounts": { "total": 11.9, "tax": 1.65, "currencyCode": "BRL" },
          "countryData": {
            "chaveAcesso": "41201008187168000160558050010000131609769080",
            "numero": "12388",
            "serie": "2",
            "modelo": 65,
            "protocolo": "135266298552102",
            "cStat": "135"
          },
          "graphic": { "qr": "41201008187168000160558050010000131609769080" },
          "providerIdentity": null,
          "providerMetadata": null
        }
      }
    }
  },
  "_meta": { "executionId": "…", "flowId": "…", "attempt": "1" }
}

Example — without an authorized document

When the order had no authorized document (the authority had not answered yet, the store does not issue documents, or the document has no provider id), the fiscal key is absent — not null. Here, a store that does not number at the till, cancelled before the authority answered: fiscalRepresentation is null, lastKnown.fiscal still says processing, and cancellation has no fiscal. No order.reversed follows. In countries that number at the till, an order cannot be cancelled while its invoice is still in force: Fire answers 409 (FISCAL_REPRESENTATION_NOT_VOIDED) until the credit note is requested. Once it is, the event carries fiscalRepresentation with the CREDIT_NOTE on top and the invoice in history.

{
  "event": { "id": "…", "type": "order.cancelled", "createdAt": "2026-09-15T14:12:03.114Z" },
  "data": {
    "orderId": "…",
    "orderCode": "OC-cl-001",
    "status": "CANCELLED",
    "paymentStatus": "SUCCEEDED",
    "store": { /* same as order.completed */ },
    "orderLines": [ /* same as order.completed */ ],
    "policy": { /* same as order.completed */ },
    "lastKnown": { "kds": null, "fiscal": { "status": "processing", "sourceEvent": "order.injected" } },
    "fiscalRepresentation": null,

    "cancellation": {
      "cancellationId": "abcf3781-c327-4df1-84ef-5efbacc1d387",
      "cancelledAt": "2026-09-15T14:12:02.870Z",
      "cancelledBy": "4fadc5f3-d9da-4756-978d-5a8cffc25d40",
      "cancellationType": "CUSTOMER_CALLED_TO_CANCEL",
      "cancellationGroup": "Customer",
      "cancellationReason": "Customer requested cancellation",
      "cancellationNote": null,
      "cancellationSource": "backoffice"
    }
  },
  "_meta": { "executionId": "…", "flowId": "…", "attempt": "1" }
}

Check it with if (data.cancellation.fiscal).

Blocks elided as same as order.completed are byte-for-byte the snapshot order.completed carries. See the order.completed field reference.

Cash fields in payments.paymentMethods[]. customerCashAmount and changeAmount are numbers. Orders injected before 24 September 2026 carry customerCashAmount as the string "0" and no changeAmount: if you replay or reprocess older events, read the field as a number. See the order.completed field reference.

`data.cancellation` reference

object

Audit block describing how, when and by whom the order was cancelled.

Show cancellation

string

UUID of this cancellation. Stable across retries, and shared with the order.reversed of the same cancellation.

string

ISO 8601 UTC timestamp of the order cancellation in Fire. It is not the authority’s authority.cancelledAt.

string

Who cancelled the order: the user’s UUID when cancellationSource is backoffice; api-key:<keyId> when it is adapter. Never null.

string | null

Stable motive code: internal catalog (ITEM_OUT_OF_STOCK, OTHER) or aggregator code (1010). Always present — null when no structured motive was set.

string | null

Motive category, internal or aggregator (SAG (IFOOD)). Always present — null when not set.

string

Free-text reason captured at cancellation time.

string | null

Optional free-text note. Always present — null when none.

string

Where the cancellation originated: backoffice or adapter.

object

Present only when the order had an authorized document with a provider id. Carries status (authorized, or cancelling if an annulment was already in flight) and authority — see The fiscal block. On this event it does not carry history, compensates, countryCode, providerCode or occurredAt; those arrive with order.reversed.

The fiscal block

For how each field of the fiscal callback lands here, see From the callback to the events. The fiscal block of order.invoiced, order.cancelled and order.reversed is what Fire stored in the order, with the same shape. It is not rebuilt per emitter: whether the document came in through your fiscal provider’s native integration or through the fiscal callback, you read the same fields at the same depth.

Where it lives in each event

Event	Path	What it carries
`order.invoiced`	`data.fiscal`	`status`, `countryCode`, `providerCode`, `occurredAt`, `authority`, `history`, `compensates`
`order.cancelled`	`data.cancellation.fiscal`	Only `status` and `authority` — no `history`, no `compensates`. Present only if the order had an `authorized` or `cancelling` document with a `providerDocId`; otherwise the key is absent
`order.reversed`	`data.cancellation.fiscal`	`status`, `countryCode`, `providerCode`, `occurredAt`, `authority`, `history`, `compensates`

On a cancellation the block sits in cancellation.fiscal, not in cancellation.metadata.fiscal. It moved up one level. If your flows or handlers read cancellation.metadata.fiscal.*, they read undefined on the current contract.

Fields of the block

string | null

The fiscal status of the order, not of one document: awaiting_payment, not_issued, pending, processing, fiscal_graphic, authorized, cancelling, cancelled, rejected, denied, error. In practice order.invoiced carries authorized, order.reversed carries cancelled, and order.cancelled carries authorized or cancelling.

string | null

ISO 3166-1 alpha-2 code of the regime that issued the document (BR, CO, EC, CL, AR, VE). The country no longer lives in the event name: filter on this field.

string | null

Fire’s identifier for the adapter that processed the document (plugnotas, generic). It is ours, not the provider’s name.

string | null

ISO 8601 UTC timestamp of the fiscal fact that fired the event, as reported by the provider.

object | null

The authority’s verdict on the current document. Fields that mean the same in every country sit at the top; the authority’s own identifiers sit in countryData, in that country’s vocabulary.

Show authority

"SALE_INVOICE" | "CREDIT_NOTE" | null

What the document is. Same vocabulary as the fiscal numbering. It replaces the old docType: "invoice" | "cancellation", which is no longer emitted.In Brazil a cancellation does not issue a new document: the same document changes state, so after order.reversed this field reads CREDIT_NOTE with the same documentNumber and access key.

string | null

The regime’s instrument: nfce, nfe, factura, boleta, factura_a. Open and referential — never branch on it.

string | null

The document’s visible number, as the authority composes it (12388, 001-020-000000123, C012001).

string | null

When the document was issued. Present on documents stored under this contract; null when unknown.

string | null

When the authority approved it — a different fact from issuedAt. Present on documents stored under this contract; null when the authority did not report it.

In Brazil the day is exact and the time is a convention. SEFAZ reports the authorization as a bare date (15/09/2026) in practically every document. Fire fills it with midnight in the store’s time zone, so authorizedAt can read earlier than issuedAt (2026-09-15T03:00:00Z against 2026-09-15T05:00:48Z). Do not use it for any calculation that needs hour precision.

string | null

When the authority approved the cancellation. Present on documents stored under this contract; null while the document is not cancelled.

"ONLINE" | "OFFLINE" | "BATCH" | null

How it was issued. OFFLINE is contingency. Not every provider has the notion.

string | null

Link to the human-readable representation (DANFE, RIDE…). Download and store it: providers may expire it.

string | null

Link to the authority’s legal XML. Same hosting as pdfUrl.

string | null

The document’s id in your fiscal provider’s system. It is what the PDF, the XML and a cancellation are fetched by.

object

The document’s amounts, in real decimals (not scaled). On documents stored under this contract the three keys are present, with null when the authority did not report the value. Orders stored before it may lack a key — treat a missing key like null.

Show amounts

number | null

Gross total.

number | null

Total tax.

string | null

ISO 4217 (BRL, COP, USD).

object | null

The authority’s own identifiers, verbatim, with the country’s own names — and only that country’s. See countryData and the fiscal callback below.

object | null

What gets printed: key → exact string to encode (qr, ted). The key names the purpose; the symbology is your template’s choice. null when there is none.

object | null

Who issued the document, as the provider reported it (provider in the fiscal callback). When present, its three keys are always there. null when the provider did not identify itself.

Show providerIdentity

string | null

Provider name (hio.fiscalization).

string | null

Issuer version.

string | null

The provider’s own reference for this document — what you quote to the provider when you ask about it.

object | null

The provider’s free-form extras (metadata in the fiscal callback), as is and opaque: Fire does not interpret it, so do not branch on it. null when absent or empty.

PlugNotas (Brazil) never sends providerIdentity or providerMetadata, so they are null. On a cancellation the block keeps the values of the previous document. Documents stored before this contract may lack both keys — treat a missing key like null.

object[]

Every stop of the order’s fiscal journey that describes a document, oldest first — including the current one. On order.invoiced it usually has one entry, equal to authority; on order.reversed it has the invoice and then the cancellation. Stops without a document block do not appear — for example the cancelling Fire records before asking the authority; a processing that already carries the till’s numbering does appear.

Show history[]

string | null

The order’s fiscal status at that stop.

string | null

When that stop happened.

string | null

Adapter that processed it.

object

The document at that stop, with exactly the shape of authority above.

This is not fiscalRepresentation.history. That one lists only the previous documents of the numbering; this one is the full journey and ends with the current document.

object | null

A pointer to the document the current one replaces. Present when the order’s fiscal status is cancelled; null otherwise. It points at the last stop in history that is not itself a cancellation — look its documentNumber up there for the whole document.

Show compensates

string | null

Visible number of the replaced document.

string | null

When that document was issued.

It carries no reason, unlike fiscalRepresentation.compensates. The motive already travels in the same event, with more detail: cancellation.cancellationType, cancellationGroup, cancellationReason, cancellationNote and cancellationSource. Fire does not emit order.reversed without an operational cancellation record, so that block is always there when compensates is. A fixed ORDER_CANCELLATION code here would say the same thing with less information. The numbering block does carry a reason: it is where the canonical code is resolved into the wording printed on the credit note, which needs the company’s own text.

In Brazil the pointer refers to the same number. SEFAZ does not number a new document to cancel one, so compensates.documentNumber equals authority.documentNumber. That is correct, not a bug.

`countryData` and the fiscal callback

countryData is one block with three names, depending on which side of Fire you look at:

Where	Name	Direction
Fiscal numbering	`countryData`	Fire → point of sale
Fiscal callback	`document`	Your provider → Fire
Order events	`authority.countryData`	Fire → you

What your provider sends in the callback’s document is what you receive in authority.countryData, with the same key names. The rule that splits the two is exclusion: every key of the callback that is not a canonical field lands in countryData untouched. That is why a country’s new identifier travels without any change on Fire’s side. The callback’s root fields become authority’s top-level fields with the same names, except the three amounts, which are grouped in amounts. provider and metadata become providerIdentity and providerMetadata (null when absent or empty). The field-by-field table is in From the callback to the events.

Brazil’s protocolo lives in countryData, not at the top. Only SEFAZ has it — Chile has trackId, Argentina the cae — so it is the authority’s vocabulary, not a canonical field. Orders stored before this contract had it at the top as authorizationProtocol; Fire emits it as countryData.protocolo for those too.

Path changes from the previous version

Previous path	Current path
`fiscal.docType` (`invoice` / `cancellation`)	`fiscal.authority.documentType` (`SALE_INVOICE` / `CREDIT_NOTE`)
`fiscal.docSubtype`, `.documentNumber`, `.providerDocId`, `.pdfUrl`, `.xmlUrl`, `.issuedAt`, `.cancelledAt`, `.authorizationMode`	`fiscal.authority.<same name>`
`fiscal.dataAutorizacao`	`fiscal.authority.authorizedAt`
`fiscal.emittedAt`	`fiscal.authority.issuedAt`
`fiscal.totalAmount` / `.taxAmount` / `.currencyCode`	`fiscal.authority.amounts.total` / `.tax` / `.currencyCode`
`fiscal.protocolo`	`fiscal.authority.countryData.protocolo`
`fiscal.chaveAcesso`, `.numero`, `.serie`, `.modelo` (BR) · `.claveAcceso`, `.establecimiento`, `.puntoEmision`, `.secuencial`, `.ambiente` (EC) · `.cufe`, `.prefijo`, `.numeroDian` (CO) · `.folio`, `.ted`, `.tipoDte`, `.trackId` (CL) · `.cae`, `.fechaVtoCae`, `.puntoVenta`, `.tipoComprobante` (AR) · `.numeroControl`, `.numeroFactura` (VE)	`fiscal.authority.countryData.<same name>`
`cancellation.metadata.fiscal.*`	`cancellation.fiscal.*` (same rules as above)
`fiscal.cStat`, `cancellation.metadata.fiscal.sefazCancellation.*`	not emitted

Every previous path has exactly one current path. The payload carries no version number: the version belongs to this documented contract.

Lifecycle relative to other events

order.cancelled is emitted immediately, before the authority is contacted.
order.reversed follows once the authority confirms — seconds or minutes later.
Without an authorized document, only order.cancelled fires.

Handler example

async function onOrderCancelled(data) {
  const { orderId, cancellation } = data;

  await db.orders.update({
    where: { fireOrderId: orderId },
    data: {
      status: "CANCELLED",
      cancelledAt: new Date(cancellation.cancelledAt),
      cancellationType: cancellation.cancellationType,
    },
  });

  // An authorized document existed: the fiscal annulment is still pending.
  if (cancellation.fiscal) {
    await reconciliation.open({
      orderId,
      document: cancellation.fiscal.authority,
      pendingAuthorityCancel: true, // closed by order.reversed
    });
  }

  await downstream.rollback(orderId);
}

Common pitfalls

Read cancellation.fiscal, not cancellation.metadata.fiscal. The previous path is empty on v3.
cancellation.fiscal is the document before the annulment. For the authority’s confirmation, listen for order.reversed.
Absent, not null. Test the key’s presence; do not compare to null.
order.cancelled is not a refund. The refund, if any, is initiated by the channel or processor.
Don’t assume order.completed arrived first. Tolerate an order.cancelled for an order you don’t know yet.

order.completed

The event you’ll see for the same order before cancellation.

order.reversed

Fires when the authority confirms the document’s cancellation.

`data.fiscalRepresentation`

Unchanged in v3. It is the fiscal numbering printed at the till, a different block from cancellation.fiscal: it never says the document was authorized. When a cancellation numbers a credit note, that note sits on top and the invoice moves into fiscalRepresentation.history. It is the same block as on order.completed — field reference in order.completed → data.fiscalRepresentation.

`data.policy` and `data.lastKnown`

Unchanged in v3 and identical to every order event. lastKnown.fiscal.status is the order’s current fiscal state and is advisory — never gate an irreversible action on it. Reference in order.completed → data.policy and data.lastKnown.

Concepts

Catalog

Trigger condition

What’s in `trigger.data`

Example — Brazil, with an authorized document (sanitized)

Example — without an authorized document

`data.cancellation` reference

The fiscal block

Where it lives in each event

Fields of the block

`countryData` and the fiscal callback

Path changes from the previous version

Lifecycle relative to other events

Handler example

Common pitfalls

order.completed

order.reversed

`data.fiscalRepresentation`

`data.policy` and `data.lastKnown`

​Trigger condition

​What’s in trigger.data

​Example — Brazil, with an authorized document (sanitized)

​Example — without an authorized document

​data.cancellation reference

​The fiscal block

​Where it lives in each event

​Fields of the block

​countryData and the fiscal callback

​Path changes from the previous version

​Lifecycle relative to other events

​Handler example

​Common pitfalls

​Related events

order.completed

order.reversed

​data.fiscalRepresentation

​data.policy and data.lastKnown

Trigger condition

What’s in `trigger.data`

Example — Brazil, with an authorized document (sanitized)

Example — without an authorized document

`data.cancellation` reference

The fiscal block

Where it lives in each event

Fields of the block

`countryData` and the fiscal callback

Path changes from the previous version

Lifecycle relative to other events

Handler example

Common pitfalls

Related events

`data.fiscalRepresentation`

`data.policy` and `data.lastKnown`