Event types for reporting
Topics are namespaced, vendor.app.resource.action, for example revenexx.orders.order.placed. 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 |
|---|---|
The event id (X-Revenexx-Event-Id) | Deduplication, and the join back to the delivery attempts in Cockpit. |
The topic (X-Revenexx-Topic) | So a later change of handling can re-process only the right rows. |
| The entity's own timestamp | Your event-time axis, from data where the topic carries one or from a re-read. A delivery does not carry the event's time. |
The raw data | Because the field you did not need today is the one somebody asks about next quarter. |
| Arrival time | Separately from the event 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 payloads stays readable.
Money, quantities and status
Three habits specific to commerce events:
- Amounts follow the topic's schema, not one platform-wide rule. An
order.placedpayload carries"grand_total": 185.16, "currency": "EUR": a decimal in the currency's major unit, €185.16. Store the amount and the currency together, exactly as they arrived, and check each topic's schema before you assume a unit. - A status in a payload is the status at that moment. An order paid later does not rewrite the
order.placedevent. 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 — revenexx.orders.order.placed.v2 alongside revenexx.orders.order.placed — 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.