Fulfillment

Delivered secrets — gift-card codes, PINs, eSIM activation values, claim tokens — are never embedded in order bodies, lists, or webhooks. They exist in exactly one place: the response of an explicit, audited reveal call. This keeps codes out of your logs, your webhook infrastructure, and every cache between us and you, until the moment you actually need them.

Reveal an order's artifacts

POST /api/v1/orders/{orderId}/fulfillment
Idempotency-Key: <1–128 printable characters>

Requires the orders.read scope and an Idempotency-Key header (same contract as order creation: identical key ⇒ identical response, safe to retry).

{
  "orderId": "0198e000-1111-7abc-9def-222233334444",
  "revealCount": 1,
  "artifacts": [
    { "type": "code", "value": "XXXX-XXXX-XXXX-XXXX", "expiresAtUtc": null }
  ]
}

Field	Meaning
`revealCount`	How many times this order has been revealed, across every channel (API, dashboard). Monitor it — a count you cannot account for means a leaked credential.
`artifacts[].type`	The artifact kind (e.g. `code`, `pin`, `url`, activation values). Treat it as an open set and render unrecognized types as opaque text.
`artifacts[].value`	The secret itself.
`artifacts[].expiresAtUtc`	Optional expiry for time-limited artifacts.

An order can carry multiple artifacts (e.g. a card number and a PIN; multi-quantity orders carry one set per unit). An order fulfilled with nothing to reveal returns an empty artifacts array.

Response codes

Status	`code`	Meaning
200	—	Artifacts returned.
400	`invalid_request`	Missing or malformed `Idempotency-Key`.
404	`not_found`	No such order in your workspace.
409	(conflict code)	The order is not in a revealable state yet (not `Fulfilled`) — wait for the `order.fulfilled` transition and retry.

The response is always sent with Cache-Control: no-store, private and Pragma: no-cache. Honor that end to end: disable response caching and body logging on any proxy in your path.

Handling secrets on your side

Reveal late. Call the endpoint when your customer or process actually needs the code, not eagerly at fulfillment time.
Store like passwords, if at all. If your product requires storing codes, encrypt them at rest with access controls and audit; if it does not, deliver and forget.
Keep codes out of telemetry. Scrub artifacts[].value from request/response logging, APM captures, and error reports.
Watch revealCount. Persist the count you expect and alert when the API reports more.
GET is not reveal. Only the POST …/fulfillment call returns values; the order body never will, so nothing sensitive rides along with routine polling.