Purchaser context - Batch Relay API

Use a retained storefront order or completed-checkout event to retrieve its transaction purchaser. The response contains only the purchaser’s name and email, an opaque reference, and availability information. It does not contain children, form answers, phone numbers, delivery recipients, or addresses.

Enable access

The Studio owner enables purchaser detail access in the Events settings of the Developer Dashboard. Access is off by default. The integration’s API key must also have the explicit events.orders.buyer.read scope. An ordinary events or print-order read scope does not grant this access. The key must currently own the event’s Studio or have an active Studio grant with the same scope. The Studio integration binding must remain active and explicitly permit buyer context. Every read rechecks these conditions. Revoking the key, Studio grant, or purchaser opt-in stops subsequent reads. Anonymous credentials cannot retrieve purchaser context.

Retrieve the purchaser

GET /v1/event-records/{event_id}/buyer
Authorization: Bearer br_test_your_test_key

Replace {event_id} with the CloudEvent id. The API resolves the Studio and order from that retained event. The credential selects the environment. A caller cannot select a different Studio or environment through this request. Example response:

{
  "order_id": "ord_example",
  "buyer_ref": "buyer_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "kind": "guest",
  "availability": "available",
  "name": "Example Purchaser",
  "email": "purchaser@example.test"
}

Field	Meaning
`order_id`	The referenced storefront order.
`buyer_ref`	Opaque Studio-scoped account reference or transaction-scoped guest reference.
`kind`	`account` or `guest`; neither implies a parent or delivery recipient.
`availability`	`available`, `missing`, or `redacted`.
`name`, `email`	Nullable transaction purchaser details.

Missing guest contact stays null. The API does not substitute the guardian account or shipping recipient. Removed purchaser details remain redacted. Responses use Cache-Control: no-store. This endpoint resolves retained Studio storefront order events. It does not assume that an API-account customer snapshot identifies a purchaser. An expired or inaccessible event, unavailable order, mismatched tenant or payment lane, or historical order with ambiguous payment mode has no available context. An absent key returns 401; missing scope or revoked integration access returns 403; unavailable event context returns 404.

Immutable events and current context

The lookup returns current authorized order context. It does not change the CloudEvent, its ID, or its historical payload. Retried and explicitly replayed events retain the original bytes. A later context lookup may return missing or redacted details even when an older lookup had contact information.

​Enable access

​Retrieve the purchaser

​Immutable events and current context

Enable access

Retrieve the purchaser

Immutable events and current context