order.reversed

v3 · current
v2 · deprecated
v1 · deprecated

You are reading the current (v3) contract for order.reversed. v3 is a breaking change in the fiscal block only: it moves from cancellation.metadata.fiscal to cancellation.fiscal, becomes structured (authority, history, compensates) and sefazCancellation is no longer emitted. The cancellation audit fields added in v2 (cancellationType, cancellationGroup, cancellationNote) are unchanged. See Path changes from the previous version.

order.reversed fires when the fiscal authority confirms the cancellation of a document it had previously authorized. It is the fiscal outcome of order.cancelled: the order is cancelled inside Fire first (order.cancelled), the cancellation is requested at the authority through your fiscal provider, and order.reversed fires only when the authority approves it.

If you need to know that the document is annulled at the authority, listen to this event — not to order.cancelled. order.cancelled is emitted when the order is cancelled, before the authority answers: its fiscal block still describes the authorized invoice. In a real Brazilian case, order.cancelled left at 05:06:45, SEFAZ approved at 05:06:51, and order.reversed left at 05:08:12.

Trigger condition

Fire emits order.reversed when a fiscal document for the order reaches cancelled — from its native provider integration or from the fiscal callback with eventType: "cancelled" — and the order has an operational cancellation record in Fire. Without that record the event is not emitted: the cancellation block is what tells consumers this is a void and not a sale.


Coverage	All countries — the country travels in `cancellation.fiscal.countryCode`
Idempotency key	`event.id`
Fires more than once	Once per active Integration Flow subscribed to the event; retried on delivery failure
Latency relative to `order.cancelled`	Usually seconds; minutes if the authority is degraded
Precondition	A previous authorized document for the same `orderId`

What’s in `trigger.data`

The same V4 order snapshot as order.completed, with status: "CANCELLED", plus the cancellation block: the same audit fields as order.cancelled and, inside it, the fiscal block with the cancelled document.

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.

Example — Brazil (NFC-e, sanitized)

{
  "event": { "id": "…", "type": "order.reversed", "createdAt": "2026-09-15T05:08:12.359Z" },
  "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 */ ],

    "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": "cancelled",
        "countryCode": "BR",
        "providerCode": "plugnotas",
        "occurredAt": "2026-09-15T05:08:11.702Z",
        "authority": {
          "documentType": "CREDIT_NOTE",
          "docSubtype": "nfce",
          "documentNumber": "12388",
          "issuedAt": "2026-09-15T05:00:48.003Z",
          "authorizedAt": "2026-09-15T03:00:00.000Z",
          "cancelledAt": "2026-09-15T05:06:51.603Z",
          "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
        },
        "history": [
          {
            "status": "authorized",
            "occurredAt": "2026-09-15T05:00:48.003Z",
            "providerCode": "plugnotas",
            "authority": { /* the invoice: documentType SALE_INVOICE, cancelledAt null */ }
          },
          {
            "status": "cancelled",
            "occurredAt": "2026-09-15T05:08:11.702Z",
            "providerCode": "plugnotas",
            "authority": { /* identical to authority above */ }
          }
        ],
        "compensates": {
          "documentNumber": "12388",
          "issuedAt": "2026-09-15T05:00:48.003Z"
        }
      }
    }
  },
  "_meta": { "executionId": "…", "flowId": "…", "attempt": "1" }
}

Note that in Brazil authority.documentNumber and compensates.documentNumber are the same (12388): SEFAZ annuls the document instead of issuing a new one. In regimes where a cancellation is a separate credit note, they differ.

`data.cancellation` reference

The audit fields are the same as in order.cancelled — including cancellationId, which both events share for the same cancellation and you can use as a join key. The fiscal block is documented below.

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

An order cancelled before its document was authorized fires only order.cancelled: there is nothing to reverse at the authority.

Handler example

async function onOrderReversed(data) {
  const { orderId, cancellation } = data;
  const fiscal = cancellation.fiscal;
  const doc = fiscal.authority;

  await db.fiscalDocs.update({
    where: { providerDocId: doc.providerDocId },
    data: {
      status: "cancelled",
      documentType: doc.documentType,
      cancelledAt: doc.cancelledAt,
      reason: cancellation.cancellationType,
    },
  });

  // The replaced document, whole, is in history.
  const replaced = fiscal.history.find(
    (e) => e.authority.documentNumber === fiscal.compensates?.documentNumber
      && e.status !== "cancelled",
  );

  await reconciliation.close(orderId, { original: replaced?.authority });
}

Common pitfalls

Read cancellation.fiscal, not cancellation.metadata.fiscal. The previous path is empty on v3.
sefazCancellation is gone. The cancellation date is authority.cancelledAt; the authority’s identifiers are in authority.countryData.
Out-of-order delivery is possible. If order.reversed arrives for an order you have no cancellation for, create it from this event’s cancellation block instead of dropping the event.
No event for a failed cancellation. If the authority rejects the cancellation, no event fires.

order.cancelled

Fires before this event — the order cancellation itself.

order.invoiced

The event that reported the document being cancelled here.

Fiscal callback

How a provider reports the cancellation that fires this event.

`data.fiscalRepresentation`

Unchanged in v3. It holds the numbers of the receipt printed at the till — the one being annulled — and it is a different block from cancellation.fiscal: fiscalRepresentation is what was numbered, authority is what the authority decided. The field reference is in the v2 page.

Concepts

Catalog

Trigger condition

What’s in `trigger.data`

Example — Brazil (NFC-e, sanitized)

`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

Handler example

Common pitfalls

order.cancelled

order.invoiced

Fiscal callback

`data.fiscalRepresentation`

​Trigger condition

​What’s in trigger.data

​Example — Brazil (NFC-e, sanitized)

​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

​Handler example

​Common pitfalls

​Related events

order.cancelled

order.invoiced

Fiscal callback

​data.fiscalRepresentation

Trigger condition

What’s in `trigger.data`

Example — Brazil (NFC-e, sanitized)

`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

Handler example

Common pitfalls

Related events

`data.fiscalRepresentation`