> ## 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.

# Purchaser context

> Retrieve a storefront transaction purchaser with an explicit Studio integration grant.

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

```http theme={null}
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:

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.