> ## Documentation Index
> Fetch the complete documentation index at: https://docs.batchrelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Public topic reference

> Public Events V1 topic names, resource subjects, and payload intent.

Every topic is a direct CloudEvents message. All examples use fictional,
production-shaped opaque identifiers and `USD` integer minor units. See
[complete examples](/events/examples) for the exact payload shapes.

## Orders

| Topic                            | Subject             | When it is emitted                                         |
| -------------------------------- | ------------------- | ---------------------------------------------------------- |
| `order.created.v1`               | `orders/{order_id}` | A durable Batch Relay order is created.                    |
| `order.paid.v1`                  | `orders/{order_id}` | Payment is durably confirmed.                              |
| `order.payment_failed.v1`        | `orders/{order_id}` | A payment attempt reaches a terminal failure state.        |
| `order.canceled.v1`              | `orders/{order_id}` | A durable post-order cancellation is recorded.             |
| `order.fulfillment_queued.v1`    | `orders/{order_id}` | Fulfillment work is queued.                                |
| `order.fulfillment_submitted.v1` | `orders/{order_id}` | Fulfillment is submitted to the selected provider.         |
| `order.fulfillment_accepted.v1`  | `orders/{order_id}` | The provider accepts the fulfillment request.              |
| `order.fulfillment_rejected.v1`  | `orders/{order_id}` | The provider rejects the fulfillment request.              |
| `order.shipped.v1`               | `orders/{order_id}` | The order's single shipment is recorded.                   |
| `order.fulfilled.v1`             | `orders/{order_id}` | All physical and digital lines finish successfully.        |
| `order.fulfillment_failed.v1`    | `orders/{order_id}` | Retries are exhausted and the fulfillment needs attention. |

Order topics are available to authorized studio/API accounts with
`events.orders.read`. The public reference does not imply a destination is
entitled to receive every topic.

## Catalog and packages

| Topic                        | Subject                           | When it is emitted                                                                              |
| ---------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------- |
| `catalog_item.changed.v1`    | `catalog-items/{catalog_item_id}` | A catalog item is created, changed, published, archived, restored, or deleted.                  |
| `package.changed.v1`         | `packages/{package_id}`           | A package summary changes lifecycle or availability.                                            |
| `catalog_batch.completed.v1` | `catalog-batches/{batch_id}`      | A bulk catalog operation completes; individual changed resources emit their own events as well. |
| `storefront.changed.v1`      | `storefronts/{storefront_id}`     | A storefront's public projection changes.                                                       |

`catalog_item.changed.v1`, `package.changed.v1`, and `storefront.changed.v1`
include both an `action` (what changed) and `state` (the resource after the
change). `action` is one of `created`, `updated`, `published`, `archived`,
`restored`, or `deleted`. `status` and `availability` are distinct fields.

Package messages are intentionally summary-only in V1: they include the package
identity, display name, pricing, and included-item count, not a nested component
catalog export.

Individual catalog-item and package events may include `batch_id`. When they are
part of a bulk operation, they use the same `batch_id` and envelope
`correlationid` as the accompanying `catalog_batch.completed.v1` summary.

## Destination tests

| Topic                 | Subject                         | When it is emitted                                            |
| --------------------- | ------------------------------- | ------------------------------------------------------------- |
| `destination.test.v1` | `destinations/{destination_id}` | A configured destination sends a requested connectivity test. |

## Common envelope extensions

| Field             | Meaning                                                |
| ----------------- | ------------------------------------------------------ |
| `environment`     | `sandbox` or `production`.                             |
| `origin`          | `storefront`, `developer_api`, or `system`.            |
| `tenantid`        | Opaque account or studio tenant identifier.            |
| `tenanttype`      | `studio` or `api_account`.                             |
| `resourceversion` | Monotonic version of the affected resource projection. |
| `correlationid`   | Required opaque ID shared by related events.           |
| `actorkind`       | `system`, `staff`, `api`, or `provider`.               |

`order.created.v1` and `order.paid.v1` include a self-contained line summary and
all five `USD` monetary components. Zero-valued discount, shipping, or tax fields
remain present. `order.payment_failed.v1` does not define monetary components;
it reports a stable failure reason instead.

Unknown object properties and unknown descriptive enum values must be tolerated
by consumers. New optional fields can be added within V1; removed fields,
changed types, changed meanings, and new required fields require a new topic
major version.