Events

Everything that happens to an order is emitted as an event: pushed to your notify_url or queue as a webhook, replayable per order on demand, and resumable across your whole stream with the event feed. One tagged union of envelopes, both directions.

The order event envelope

Event shapes are a tagged union on event_type, with two fields common to every type: event_type and occurred_at. The exact field set per variant is defined once, in the canonical model (tech spec section 10 point 1); this table and the order event reference restate that one contract for the order event envelope, carried by order.status_changed alone. The standalone types carry their own envelopes, defined with the type table below, because an event about a catalog window or an ingest rejection has no order to identify: forcing order_id, seq, and status onto it would make the fields lies.

{
  "event_type": "order.status_changed",
  "order_id": "ord_9f3a12c4b7e1",
  "external_order_id": "q4-campaign-042",
  "buyer_entity": "yourco",
  "seq": 5,
  "status": "placed",
  "prior_status": "seller_review",
  "substatus": null,
  "units": [
    {
      "unit_id": "u-0001",
      "status": "accepted",
      "num_accepted": 10,
      "reason": null,
      "allocation": [
        { "date": "2026-10-05", "units": 4 },
        { "date": "2026-10-07", "units": 3 },
        { "date": "2026-10-09", "units": 3 }
      ]
    },
    {
      "unit_id": "u-0002",
      "status": "accepted",
      "num_accepted": 10,
      "reason": null,
      "allocation": [
        { "date": "2026-10-06", "units": 10 }
      ]
    }
  ],
  "artifact": {
    "name": "placement_receipt",
    "seller_order_id": "ACME-77120",
    "daylocks": [
      {
        "unit_id": "u-0001",
        "date": "2026-10-05",
        "units": 4
      },
      {
        "unit_id": "u-0001",
        "date": "2026-10-07",
        "units": 3
      },
      {
        "unit_id": "u-0001",
        "date": "2026-10-09",
        "units": 3
      },
      {
        "unit_id": "u-0002",
        "date": "2026-10-06",
        "units": 10
      }
    ],
    "placed_at": "2026-10-02T14:41:09Z"
  },
  "approval": {
    "gate": "seller_review",
    "actor": "sales@acmebroadcasting.example",
    "decision": "approve"
  },
  "error": null,
  "occurred_at": "2026-10-02T14:41:09Z"
}

Webhook deliveries are signed (X-Signature) and numbered (X-Delivery-Attempt); see verifying the signature.

Event types

Six types, one per genuinely distinct kind of happening: one lifecycle type, one order-linked notice, and four standalone types, each with the envelope its subject can truthfully fill.

These five non-lifecycle types stay types because they are not order transitions at all: nothing on the order's status machine moved, so there is no status for a filter to name. Each carries its own envelope beside the two common fields. catalog.stale_rate_card is an order-linked notice, not an order-stream event: its exact field set is the canonical model's: {event_type, order_id, external_order_id, buyer_entity?, rate_version, superseded_by, drift[], occurred_at}, dedup on (order_id, superseded_by), and it is absent from per-order replay, because nothing on the order's status machine moved and its recovery path is arithmetic rather than history: the drift is recomputable any time from the snapshot's locked prices against the live card. catalog.window_opened carries {seller, product_id, week, window, signal?}, dedup on (product_id, window.opens); catalog.integrity_failed carries {seller, commit or drop id, conflict report}, dedup on the rejected commit or drop id; settlement.invoice_issued carries {invoice_id, order_id, external_order_id}, dedup on invoice_id; and avails.answered keeps the envelope it always had ({avails_request_id, seller_id, state, occurred_at}, dedup on avails_request_id, absent from order replay). None of them carries seq or status: those are order-stream facts.

Who receives which transitions

The collapse renames types; it does not widen who hears what. Delivery and replay stay audience-projected from one stored log, exactly as before, and the eligibility is now stated as a matrix instead of being implied by type names. The one deliberate widening is named in the last row.

Replay under each credential returns exactly that credential's eligible subset, so a replay never shows a side more than its deliveries did. Stored webhook registrations carrying retired type names keep working, migrated once at read time: order.needs_review reads as events: ["order.status_changed"], statuses: ["seller_review"], negotiation.offer as statuses: ["negotiating"], order.canceled as statuses: ["canceled"]. Role never travels in the filter: a registration belongs to a tenant whose role the platform knows, and eligibility applies before any filter does.

GET /v1/events: replay

GET/v1/eventsorders:write or orders:approve

Replay an order's event history: the recovery path when webhook deliveries are missed. The order snapshot carries last_seq; replay everything after your high-water mark and the loop is closed. Replay is per order; to resume your whole stream across every order at once, use the feed below. The order's seller may replay it too, which is the replay half of the same eventing that reaches both directions. Both sides read the same event_type: the whole envelope, seq, status, and prior_status included, is identical for both.

Query parameters

Response

Events in seq order, plus the order's current last_seq so you know when you are caught up. Replay re-shapes nothing. Each replayed item is the stored envelope with exactly two fields removed: order_id and external_order_id, hoisted once to the top of the response because every event in it belongs to the one order you named. No other field is projected away: the conditional payloads (units, artifact, approval, copy, attachments, cancellation, superseded_by, error) replay exactly as they were delivered, which is what makes replay a real recovery path rather than a summary of one. Compare the second event below against the webhook example above: it is the same event, differing only by the two hoisted identifiers. The only other selection is audience eligibility: it decides which events a credential replays, never what a replayed event contains.

200 Response
Timestamps in these examples are illustrative. The sandbox stamps every event, receipt, and as_of at the moment of the call, so a response you get back carries today's instant rather than the one printed here. What the examples fix is the shape and the ordering: stamps on one order are strictly increasing, and two calls a minute apart are a minute apart in the log.
{
  "order_id": "ord_9f3a12c4b7e1",
  "external_order_id": "q4-campaign-042",
  "events": [
    {
      "event_type": "order.status_changed",
      "buyer_entity": "yourco",
      "seq": 1,
      "status": "submitted",
      "prior_status": "draft",
      "substatus": null,
      "artifact": null,
      "error": null,
      "occurred_at": "2026-10-01T14:02:11Z"
    },
    {
      "event_type": "order.status_changed",
      "buyer_entity": "yourco",
      "seq": 5,
      "status": "placed",
      "prior_status": "seller_review",
      "substatus": null,
      "units": [
        {
          "unit_id": "u-0001",
          "status": "accepted",
          "num_accepted": 10,
          "reason": null,
          "allocation": [
            { "date": "2026-10-05", "units": 4 },
            { "date": "2026-10-07", "units": 3 },
            { "date": "2026-10-09", "units": 3 }
          ]
        },
        {
          "unit_id": "u-0002",
          "status": "accepted",
          "num_accepted": 10,
          "reason": null,
          "allocation": [
            { "date": "2026-10-06", "units": 10 }
          ]
        }
      ],
      "artifact": {
        "name": "placement_receipt",
        "seller_order_id": "ACME-77120",
        "daylocks": [
          {
            "unit_id": "u-0001",
            "date": "2026-10-05",
            "units": 4
          },
          {
            "unit_id": "u-0001",
            "date": "2026-10-07",
            "units": 3
          },
          {
            "unit_id": "u-0001",
            "date": "2026-10-09",
            "units": 3
          },
          {
            "unit_id": "u-0002",
            "date": "2026-10-06",
            "units": 10
          }
        ],
        "placed_at": "2026-10-02T14:41:09Z"
      },
      "approval": {
        "gate": "seller_review",
        "actor": "sales@acmebroadcasting.example",
        "decision": "approve"
      },
      "error": null,
      "occurred_at": "2026-10-02T14:41:09Z"
    }
  ],
  "last_seq": 5
}

Errors

GET /v1/events/feed: the resumable stream

GET/v1/events/feedorders:write or orders:approve

Your whole event stream, resumable. Webhooks are push-only, so a subscriber that was down has no way to be caught up by them; per-order replay closes one order's gap but makes a subscriber with 500 live orders poll 500 histories. The feed is the third read on the same stored log: every event a webhook would deliver to your credential, in the order they were recorded for you, from wherever you left off. Keep the returned cursor beside your high-water marks and recovery after any outage is one loop.

The feed is delivery's pull twin, not an order history. It carries exactly what push delivery carries: all six event types, each in the same envelope a webhook delivers, with both order identifiers on lifecycle events (nothing is hoisted here, because the feed spans orders). So the standalone types that per-order replay excludes, catalog.stale_rate_card and avails.answered among them, do appear on the feed, exactly when a webhook would have delivered them: "absent from per-order replay" is a statement about an order's history, and the feed is not an order's history. Audience eligibility applies before anything else, as everywhere: each stream is its own eligible view of the platform's log and nothing more.

The stream and its cursor belong to your organization and role, never to your token. There is one stream per organization per role, because the eligibility matrix is role-shaped, and the request names which one it reads: the role parameter selects the buyer or the seller stream, and the token must hold that role's order scope (orders:write for the buyer stream, orders:approve for the seller stream, per the scope table). A token whose scopes admit only one role may omit role and gets that stream; a token holding both scopes must say which stream it is reading, because a scope set is a set of grants, not an instruction, and the first read of a stream has no cursor to disambiguate it. An organization on both sides of the marketplace therefore has two streams that never mix. A cursor names a position in one stream, so it survives token refresh and signing-key rotation: any credential resolving to the same organization and role with the right scope resumes exactly where the last one stopped. What a cursor never survives is a change of whose stream it is: presented against a different organization's stream, the other role's stream, or never issued at all, it answers the identical 422 INVALID_INPUT, indistinguishable from a malformed cursor, so a cursor can neither be borrowed across a tenant or role boundary nor probed for validity (the same fail-closed posture as the credit lookup). If your eligibility changes while a cursor is held, the cursor stays valid and reads from it simply apply current eligibility from that position forward: eligibility decides which events you get, never what a cursor is. Per-order replay follows the same scope rule: the order's buyer replays under orders:write, its seller under orders:approve.

Least privilege holds inside the stream. The role's order scope admits you to the stream and its order.status_changed items; the non-lifecycle types additionally require the scope that governs their domain, and a token lacking it simply does not receive them: settlement.invoice_issued requires settlement:read; catalog.integrity_failed requires catalog:write (the scope that published what failed); catalog.stale_rate_card, catalog.window_opened, and avails.answered require catalog:read. So an orders-only token reads an orders-only feed, and the feed under a full-scope token is exactly what push delivery carries, because webhook delivery is registered by the organization while a token speaks only for its own grants. Scope-skipped items behave exactly as filter-skipped items do: the returned cursor advances past them, and a later, broader token resuming from that cursor does not get them back.

Query parameters

Response

Items in position order, plus the cursor to resume from and whether more is waiting. The feed re-shapes nothing, exactly as replay re-shapes nothing: each item is the stored envelope as delivery carries it, every conditional payload included.

200 Response
{
  "events": [
    {
      "event_type": "order.status_changed",
      "order_id": "ord_9f3a12c4b7e1",
      "external_order_id": "q4-campaign-042",
      "buyer_entity": "yourco",
      "seq": 1,
      "status": "submitted",
      "prior_status": "draft",
      "substatus": null,
      "artifact": null,
      "error": null,
      "occurred_at": "2026-10-01T14:02:11Z"
    },
    {
      "event_type": "avails.answered",
      "avails_request_id": "avr_7d21",
      "seller_id": "acme",
      "state": "answered",
      "occurred_at": "2026-10-01T15:40:02Z"
    }
  ],
  "cursor": "evc_000000000217",
  "has_more": false
}

Errors