Event types for reporting
Topics are named resource.action, or vendor.app.resource.action for events an App publishes. The naming, the payload conventions and how payloads evolve are documented in Event types — read that first.
Which topics are worth subscribing to
Rather than a list that goes stale, the question to ask of each topic in your tenant's catalog:
Does it change a number I report? Subscribe. Does it only change something I would look up anyway? Skip it, and re-read the entity when you need it.
The commerce topics that usually pass that test are the lifecycle transitions — an order created, an order paid, a customer activated, stock changed, pricing updated. Those are the moments a figure moves. The ones that usually fail it are the internal state changes that do not alter any total.
Subscribe to exactly what you need. An endpoint subscribed to everything is a receiver you have to make fast, idempotent and correct for events you will never look at.
What to record when one arrives
Write down more than the number you are after. The minimum that stays useful:
| Record | Why |
|---|---|
id | Deduplication, and the join back to the delivery log. |
topic | So a later change of handling can re-process only the right rows. |
time | Your event-time axis. Not the arrival time. |
The raw data | Because the field you did not need today is the one somebody asks about next quarter. |
| Arrival time | Separately from time, for diagnosing lag. |
Storing the raw payload as received costs almost nothing and saves a re-backfill. Payloads evolve additively — a topic's data only ever gains fields — so an archive of raw envelopes stays readable.
Money, quantities and status
Three habits specific to commerce events:
- Amounts are integers in a currency's minor unit. An
order.createdpayload carrying"total": 14990, "currency": "EUR"is €149.90. Store the integer and the currency together; never divide before you store. - A status in a payload is the status at that moment. An order paid later does not rewrite the
order.createdevent. If you need current status, the event is the trigger and the API is the answer. - A quantity change is a delta or a level depending on the topic. Check the payload schema for your tenant rather than assuming; getting this wrong turns a stock report into fiction.
Versioned topics
A breaking change to a payload ships as a new topic with a version suffix — order.created.v2 alongside order.created — and both run side by side until you migrate. For a reporting pipeline that is a gift: subscribe to the new topic, backfill the overlap from the API, and switch your reader over without a flag day.
App events
An App declares the events it publishes in its manifest, which makes those names part of the app's public contract. If you are both the app author and the one reporting on it, that is the cleanest feed you will get: you control the topic, the payload and the cadence. See App Studio.
Where to go next
- Event types — topic naming, payload evolution, and finding your tenant's catalog.
- Verify a delivery — before you trust any of the above.
- Modelling — turning these records into something you can report on.