Event types

Every event carries a topic that names what happened. This page explains how topics are structured, what's in a payload, and how to find the precise list of events your tenant emits.

How topics are named

A topic is a dot-separated, lowercase name with at least two segments. There are two forms, and both are valid:

• resource.action — the common short form. The resource first, the action second.
  resource.action

  order.created
  order.paid
  customer.activated
  inventory.stock_changed
  pricing.updated
  

• vendor.app.resource.action — the namespaced form that custom Apps use for the events they publish, so two apps can't clash on a name.
  namespaced

  acme.billing.invoice.settled
  

When you subscribe — from an App manifest or a Webhook destination — you name the topics you want. You receive those and nothing else.

What's in a payload

The data object holds the payload, and its fields depend on the topic. An order.created event carries order fields; a customer.activated event carries customer fields. Treat each topic's data shape as a contract: the publisher adds fields over time, but won't remove or repurpose existing ones without changing the topic.

{
  "tenant_id": "acme-eu",
  "topic": "order.created",
  "id": "evt_01jc8m4yq2…",
  "data": {
    "order_id": "o_8421",
    "status": "pending",
    "total": 14990,
    "currency": "EUR"
  },
  "metadata": {},
  "time": "2026-05-31T10:00:00Z"
}

How payloads change over time

Payloads evolve additively. A topic's data only ever gains fields; existing fields keep their meaning. So a handler written against order.created today keeps working when new fields appear — read the fields you need and ignore the rest.

A change that would break that rule — removing a field, changing a type — ships as a new topic, not a silent change to the old one. The convention is a version suffix:

order.created        # original
order.created.v2     # breaking change — a separate topic you opt into

Both topics then run side by side until you migrate, so an upgrade is never a flag day.

Finding the catalog for your tenant

The set of topics is determined by your tenant: the core commerce capabilities emit a standard set, and any custom App you install adds its own. An app declares the events it publishes in its manifest (events.emits), which makes those names part of the app's public contract.

To see the topics available right now and inspect their payloads, use the API Explorer for your tenant.

Where to go next

• Consuming events — react to these topics from an App or a Webhook.
• Webhooks — receive selected topics at your own endpoint.
• App manifest reference — declare the topics an app emits and subscribes to.