order.invoiced

v1.2 · current
v1.1 · previous
v1 · deprecated
v0 · deprecated

You are reading the current (v1.2) contract for order.invoiced. v1.2 adds data.fiscalRepresentation: the fiscal numbering the point of sale obtained before injecting the order. It always travels: null when numbering was not attempted, and populated when it was — numberingStatus tells you how it ended. Carrying content does not mean the document is authorized. Additive only — nothing you already read changed.The block carries the order’s current fiscal document: the fields that mean the same in every country at the top, the authority identifiers inside countryData in that country’s own vocabulary, and the previous documents in history. When a cancellation numbers, the credit note moves to the top and the invoice moves down into history — with compensates pointing at it.

v1.1 added data.policy.deferredPayment (can this order be worked before payment?) and data.lastKnown (advisory kitchen/fiscal state), plus the new order.opened event. Still valid: v1.2 only adds one block.

The v1 contract is deprecated — kept as a historical reference. Open it here: order.invoiced — v1.

order.invoiced fires once the country’s fiscal authority authorizes the fiscal document associated with an order — SEFAZ in Brazil, SRI in Ecuador, DIAN in Colombia, AFIP in Argentina, SII in Chile, SENIAT in Venezuela. It is emitted by Fire’s fiscal pipeline, which integrates with your fiscal provider as the document provider. This event is separate from order.completed: the order is paid first (order.completed), then Fire requests fiscal emission via your fiscal provider, and order.invoiced fires only when the fiscal authority returns the authorization.

Trigger condition

Fire emits order.invoiced once per fiscal document, the first time all of these are true:

The order is in a store with fiscal billing enabled (storeFiscalConfig.enabled === true)
A fiscal document was emitted to your fiscal provider
your fiscal provider reports that the fiscal authority authorized the document (status transitions to authorized; in Brazil this maps to the SEFAZ cStat authorized code)


Coverage	All countries — Brazil (NFC-e/NF-e via SEFAZ) and CO/EC/CL/AR/VE via the generic fiscal callback. The country travels in `fiscal.countryCode`, no longer in the event name
Document types	Vary by country — `nfce`/`nfe` (BR), electronic invoice (CO/EC/CL/AR/VE). Arrives in `fiscal.docSubtype`
Idempotency key	`event.id`
Fires more than once	No, unless retried
Latency relative to `order.completed`	Usually seconds; can be minutes if the fiscal authority is degraded

What’s in `trigger.data`

Same V4 order snapshot as order.completed plus a top-level fiscal block carrying the authorized document references. Fields vary by country — Brazil is shown below (chaveAcesso, protocolo); other countries carry their own identifiers (cufe in CO, claveAcceso in EC, cae in AR, etc.). See the generic fiscal callback for the per-country contract. The order’s status remains "COMPLETED" and paymentStatus remains "SUCCEEDED" — fiscal authorization does not change order status.

Example — real production payload (BR, sanitized)

{
  "event": {
    "id": "...",
    "type": "order.invoiced",
    "createdAt": "2026-05-06T01:23:11.000Z"
  },
  "data": {
    "orderId": "8017b54c-af0c-4246-a60a-a0d4ae9a0fef",
    "orderCode": "OC-br-001",
    "businessDayDate": "2026-03-31",
    "externalOrderId": "8017b54c-af0c-4246-a60a-a0d4ae9a0fef",
    "status": "COMPLETED",
    "paymentStatus": "SUCCEEDED",
    "createdAt": "2026-05-06T01:22:56.488Z",
    "store": { /* same as order.completed — includes storeFiscalConfig with CNPJ, legalName */ },
    "client": { /* ... */ },
    "payments": { /* ... — includes payments.metadata.fiscal aggregates */ },
    "orderLines": [ /* ... */ ],
    "fulfillment": { /* ... */ },
    "device": { /* ... */ },
    "channel": { /* ... */ },
    "operator": { /* ... */ },
    "kds": { /* ... */ },
    "marketing": null,
    "metadata": {},

    "fiscal": {
      "status": "authorized",
      "docSubtype": "nfce",
      "chaveAcesso": "41201008187168000160558050010000131609769080",
      "numero": "1000013",
      "protocolo": "141200000956123",
      "providerDocId": "69fa97fe427d1240856e1282",
      "pdfUrl": "https://api.fiscal-provider.example/nfce/69fa97fe427d1240856e1282/pdf",
      "xmlUrl": "https://api.fiscal-provider.example/nfce/69fa97fe427d1240856e1282/xml",
      "dataAutorizacao": "2026-05-06T01:23:10.991Z",
      "cStat": null
    }
  },
  "_meta": { "executionId": "...", "flowId": "...", "attempt": "1" }
}

`data.fiscal` reference

object

SEFAZ-authorized document references.

Show fiscal

string

Document status. For this event, always "authorized". Other values you may see in your fiscal provider (pending, processing, rejected, denied) do not trigger order.invoiced — only the terminal authorized state does.

string

Document type. Values: nfce (NFC-e — consumer invoice, B2C) or nfe (NF-e — business invoice, B2B).

string

The 44-digit SEFAZ access key. Encodes UF, year/month, CNPJ, model, series, number, type of emission, and a check digit. Use this for reconciliation with SEFAZ portals.

string

Document number assigned by Fire’s emission pipeline. Sequential per (cnpj, serie, docSubtype).

string | null

Document series. May be null for some configurations; the series is encoded in chaveAcesso regardless.

string

SEFAZ authorization protocol number. Required for any subsequent SEFAZ operation (cancellation, correction).

string

Internal document ID assigned by your fiscal provider. Use it to query your provider’s APIs directly (e.g. fetch the canonical XML).

string

URL to download the document’s PDF (DANFE for NF-e, DANFCE for NFC-e). Hosted by your fiscal provider; signed/short-lived in production, durable in sandbox.

string

URL to download the canonical SEFAZ XML. Same hosting as pdfUrl.

string

ISO 8601 UTC timestamp of the SEFAZ authorization (when SEFAZ stamped the protocol).

string | null

Raw SEFAZ status code. May be null when the provider does not surface it (some providers hide it for consumer flows). When present, 100 (NF-e) or 100 (NFC-e) indicate authorization.

Where the fiscal totals live

The aggregate fiscal values (vBC, vNF, vICMS, etc.) are not inside data.fiscal — they’re in data.payments.metadata.fiscal, the same place order.completed carries them. order.invoiced does not duplicate them; treat the order snapshot as the single source of truth for monetary aggregates. Per-line classification (NCM, CFOP, CSOSN, fiscalCategoryCode) lives in data.orderLines[n].metadata.fiscal. Same as in order.completed. The data.store.storeFiscalConfig block carries the emitter identity (CNPJ, legalName, tradeName) — also unchanged from order.completed.

`data.policy` and `data.lastKnown`

Every order event carries these two blocks — not just this one. They were added together with the deferred-payment cycle and are added in v1.1, additive: existing consumers keep working unchanged.

Block	What it is	Trust it?
`policy.deferredPayment`	Whether the order may be acted on before payment. Resolved once at injection and stamped immutably — every later event echoes the same value.	Yes. It is a decision, not a state.
`lastKnown`	Advisory snapshot of kitchen (`kds`) and fiscal state when the event was emitted. May be `null` or stale.	No. Never gate an irreversible action on it.

"policy": { "deferredPayment": { "eligible": true, "resolvedAt": "2026-08-02T15:55:42.407Z",
    "configVersion": "fnv1a:3144c6fb",
    "resolvedFrom": { "channelCode": "APP", "fulfillmentCode": "DELIVERY", "paymentMethod": "CASH" } } },
"lastKnown": { "kds": null, "fiscal": { "status": "processing", "sourceEvent": "fiscal.callback" } }

Field-by-field detail lives in order.opened, the event where these blocks matter most.

Handler example

async function onFiscalAuthorized(data) {
  const { orderId, fiscal, store } = data;

  // 1. Persist the SEFAZ authorization for audit
  await db.fiscalDocs.upsert({
    where: { providerDocId: fiscal.providerDocId },
    create: {
      providerDocId: fiscal.providerDocId,
      fireOrderId: orderId,
      country: "BR",
      cnpj: store.storeFiscalConfig.govIdNumber,
      docSubtype: fiscal.docSubtype,
      chaveAcesso: fiscal.chaveAcesso,
      protocolo: fiscal.protocolo,
      authorizedAt: new Date(fiscal.dataAutorizacao),
      status: "authorized",
    },
    update: {},
  });

  // 2. Fetch the canonical XML for archival (legally required in BR)
  const xml = await fetch(fiscal.xmlUrl).then(r => r.text());
  await archive.put(`xml/${fiscal.providerDocId}.xml`, xml);

  // 3. Notify the customer with the PDF link
  await mailer.send({
    to: data.client?.email,
    template: "fiscal-receipt",
    pdf: fiscal.pdfUrl,
  });
}

Common pitfalls

status === "authorized", not "COMPLETED". The data.status (the order status) is "COMPLETED"; the fiscal status is in data.fiscal.status.
pdfUrl and xmlUrl may be ephemeral. In production, your fiscal provider may sign/expire these links. Download and persist the artifacts on receipt rather than linking customers directly to your fiscal provider.
cStat is often null. Don’t make logic depend on it. Use status === "authorized" and protocolo as the authoritative signals.
No event for rejected / denied / error. If SEFAZ rejects the document, no event fires today. The fiscal document’s status is persisted internally but no flow is triggered. Watch for this in the roadmap.
The country no longer lives in the event name. order.invoiced fires for all countries; filter on fiscal.countryCode. The fiscal block fields vary per country (chaveAcesso/protocolo in BR, cufe in CO, claveAcceso in EC, etc.).

order.completed

Fires before this event — the order itself.

order.reversed

Fires later if the document gets cancelled at SEFAZ.

`data.fiscalRepresentation`

The fiscal numbering the point of sale obtained before injecting the order: it charges, requests the identifiers, prints the receipt, and only then injects. That is why it travels on the order and not in a separate fiscal event — by the time the order is born, this already happened.

The presence of this block does NOT mean the document is authorized. These are the numbers printed at the till; the tax authority’s verdict is in lastKnown.fiscal.status. A ticket that says “authorized” just because the block is present states something that may never have happened.

The key always travels. It arrives as null when numbering was not attempted — aggregators, countries without fiscal representation, or merchants with numbering turned off — and carries the block when it was. Carrying the block means numbering was attempted, not that it succeeded: numberingStatus tells you how the attempt ended, and failure why, when it did not end well. Branch on the value, not on the key’s presence:

if (data.fiscalRepresentation) {
  // numbering was attempted — read numberingStatus to see how it went
}

Field	What it is
`numberingStatus`	How the numbering act ended: `GENERATED`, `PENDING`, `FAILED_RETRYABLE`, `FAILED_FINAL`, `UNAVAILABLE`. Not the authority’s verdict — that lives in `lastKnown.fiscal.status`.
`documentNumber`	The receipt’s visible number, composed per country (`005-004-000000042`). It is presentation and Fire builds it, not the authority: reconcile with `countryData`.
`issuedAt`	When it was numbered. Not the authorization date.
`authorizationMode`	`ONLINE`, `OFFLINE` or `BATCH`. A provider concept, not universal.
`providerCode`	Identifier of the adapter that numbered.
`countryData`	The authority identifiers, in the vocabulary of the country that numbered — and only that country’s. Ecuador: `numeroComprobante` (the human-readable document number, already assembled by the provider), `claveAcceso`, `establecimiento`, `puntoEmision`, `secuencial`, `ambiente`. Venezuela: `numeroControl`, `numeroFactura`, `serie`. Iterate it; do not index blindly — a new key here is not a breaking change. It is the same block the numbering endpoint returns and the authority callback carries. The per-country reference, with each regime’s keys, is in `countryData` by country.
`graphic`	The printable artifact the provider returned (QR and the like), verbatim. `null` if it returned none.
`failure`	Why there is no receipt. `null` when numbering succeeded.
`providerIdentity`	Who numbered, on the provider’s side: `{ "name": "hio.fiscalization", "version": "2026.08.1", "reference": "HIO-91f3c2" }`. Unlike the bag below, it has a shape: all three fields are part of the contract and always come through, with `null` when they do not apply. `reference` is the provider’s own support reference — the identifier you quote back to them so they can find the operation in their records; it is not the `Idempotency-Key` the channel sent. It does not carry `providerCode`: that one is ours and travels at the top.
`providerMetadata`	The provider’s diagnostic bag, exactly as it returned it: in Ecuador with HIO you get `{ "deviceUid": "4B8E…", "externalStoreCode": "K000" }`. It is opaque — the provider owns the keys and may change them without notice, so do not program against them; it is for pasting into a ticket, not for branching. It is exactly the same field the numbering endpoint returns, same name and same content: all three provider fields read the same at both ends.
`environment`	Which environment Fire numbered in: `SANDBOX` or `PRODUCTION`. It is ours, not the authority’s — the authority’s travels inside `countryData` with the country’s own code.
`compensates`	Which document this one voids. Present only when `documentType` is `CREDIT_NOTE`. It is a pointer, not a copy: look its `documentNumber` up in `history` for the whole document. `reason` is the canonical code — the printed wording is authored per company and resolved in the numbering endpoint’s response.
`history`	The order’s previous documents, oldest first. Empty while there was only one; when a cancellation numbers, the invoice moves down here and the credit note sits on top. Every entry has the same shape as the block above, so they read alike. Documents only: a failed attempt does not appear.

"fiscalRepresentation": {
  "numberingStatus": "GENERATED",
  "documentNumber": "005-004-000000042",
  "countryData": {
    "numeroComprobante": "005-004-000000042",
    "claveAcceso": "1208202601000000000000110050040000000421234567810",
    "establecimiento": "005",
    "puntoEmision": "004",
    "secuencial": "000000042",
    "ambiente": "2"
  },
  "authorizationMode": "ONLINE",
  "issuedAt": "2026-08-13T08:11:29.744Z",
  "providerCode": "hio",
  "graphic": { "qr": "1208202601000000000000110050040000000421234567810" },
  "failure": null,
  "providerIdentity": { "name": "hio.fiscalization", "version": "2026.08.1", "reference": "HIO-91f3c2" },
  "providerMetadata": { "deviceUid": "4B8E21F9A0D35C7A", "externalStoreCode": "K004" },
  "environment": "PRODUCTION",
  "compensates": null,
  "history": []
}

The authority’s verdict does not alter it. What the customer took home printed does not change because the authority later authorizes or rejects — that is what lastKnown.fiscal is for, and that is what does move. What does replace it is a new document. The block carries the order’s current fiscal document. While there was only one, it was always the invoice; when a cancellation produces a credit note, the note is what sits on top — documentType says which one — and the invoice moves down into history, whole and with its own authority identifiers. It is not lost: it moves. compensates points at it by number, so the relationship stays explicit.

When numbering fails

A sale can be charged and end up with no fiscal receipt. That case travels too, and you must handle it: the identifiers come back null and the reason is in failure.

"fiscalRepresentation": {
  "numberingStatus": "FAILED_FINAL",
  "documentNumber": null,
  "issuedAt": null,
  "providerCode": "hio",
  "graphic": null,
  "failure": { "code": "RUC_INVALIDO", "scope": "FUNCTIONAL", "message": "Tax ID not enabled" }
}

Branch on failure.scope:

TECHNICAL — print “pending” and carry on. It may resolve on its own.
FUNCTIONAL — some data is wrong and retrying will not fix it. Needs correction.

lastKnown.fiscal.sourceEvent now reports real provenance. It used to be derived from the status, so a processing seeded at injection was reported as fiscal.callback even though no callback had occurred. That case now says order.injected. If you branch on this field, account for the new value.

Concepts

Catalog

Trigger condition

What’s in `trigger.data`

Example — real production payload (BR, sanitized)

`data.fiscal` reference

Where the fiscal totals live

`data.policy` and `data.lastKnown`

Handler example

Common pitfalls

order.completed

order.reversed

`data.fiscalRepresentation`

When numbering fails

​Trigger condition

​What’s in trigger.data

​Example — real production payload (BR, sanitized)

​data.fiscal reference

​Where the fiscal totals live

​data.policy and data.lastKnown

​Handler example

​Common pitfalls

​Related events

order.completed

order.reversed

​data.fiscalRepresentation

​When numbering fails

Trigger condition

What’s in `trigger.data`

Example — real production payload (BR, sanitized)

`data.fiscal` reference

Where the fiscal totals live

`data.policy` and `data.lastKnown`

Handler example

Common pitfalls

Related events

`data.fiscalRepresentation`

When numbering fails