Public topic reference - Batch Relay API

Every topic is a direct CloudEvents message. All examples use fictional, production-shaped opaque identifiers and USD integer minor units. See complete 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.

​Orders

​Catalog and packages

​Destination tests

​Common envelope extensions

Orders

Catalog and packages

Destination tests

Common envelope extensions