Identifiers and error types

An offering carries more than one identifier, and each call accepts a specific one. This page is the reference for which id goes where, and for the typed error responses — RFC 7807 application/problem+json — your integration meets along the way.

Identifiers

Every offering has two machine identifiers. The catalog console shows both on an offering’s detail screen, each one copyable and labeled by the call that accepts it — so you never have to guess one or compose it by hand.

Identifier	What it is	Accepted by
`sku_id`	The offering’s stable machine id, shaped `sku_…`. It is derived from the offering code — never composed by hand.	`POST /v1/prospects`, which opens an enrollment for a direct-buy start.
`offering_ref`	The offering reference. In this version it is exactly the catalog offering code — the same human-readable code you see on the offering’s detail screen, for example `SYN-TRZ-3M`.	`GET /v1/promotions/merchandising` and `POST /v1/payments/checkout-sessions`.

The code you read on an offering screen (SYN-TRZ-3M) is the offering_ref — there is no separate lookup, and no display-versus-machine split for it in this version. Pass that code wherever an offering_ref is asked for. The sku_id is a different string (sku_…); it is the id the prospect-capture call expects, not the merchandising or checkout call. Of these calls, POST /v1/payments/checkout-sessions and GET /v1/payments/{order_ref}/status appear on the API reference tab. The merchandising read and prospect capture are not in the published reference: prospect capture (POST /v1/prospects) is made by the platform’s own hosted checkout on its server, so your storefront never calls it directly.

The enrollment thread

A patient’s enrollment carries a journey_id (shaped jny_…), minted the first time an intake session resolves. On the hosted platform it travels in the X-Journey-Id request header — that header is how the platform threads one patient’s context across calls. Send it back on a later GET /v1/instrument/resolve to pick an in-progress questionnaire up where the patient left off, and it is the same id you see on webhook events and on the enrollment status read (GET /v1/journeys/{journey_id}/status). The X-Journey-Id header is what the hosted platform reads to resume; a journey_id query parameter is honored only by the standalone renderer used for direct testing, so build against the header.

Problem responses

Every refusal is an application/problem+json body: a stable type, a short title, and the HTTP status repeated in the body. Switch on the type — it is the stable, machine-readable part.

The API-key wall

The platform’s key-protected reads — for example, your account’s orders — sit behind your API key in an Authorization: Bearer header, scoped to a brand you own with X-Brand-Id:

A request with no key is refused 401 https://purple.md/problems/unauthenticated.
A valid key paired with a brand that is not yours is refused 404 https://purple.md/problems/brand-not-found — never 403, so a brand’s existence never leaks across tenants.

The typed responses you will meet

`type`	`status`	What it means
`commerce/merchandising/not-configured`	`404`	The brand-and-offering pair has no merchandising configured. Configure its pricing — the path and the offering are fine.
`commerce/checkout/unknown-offering`	`404`	The `offering_ref` does not resolve for this brand. Check the code, or the brand’s catalog.
`commerce/checkout/client-authored-charge-parameter`	`422`	The checkout body carried a money field — a price, a fee, or a topology. The server re-resolves every money figure from your configured catalog; the only accepted body keys are `offering_ref`, `journey_id`, and an optional `promo`.
`commerce/checkout/card-data-unconstructible`	`422`	A card-shaped field was present. No call accepts a card number; card capture happens only on the hosted page.
`commerce/checkout/promo-validation-unavailable`	`422`	A `promo` token was sent but cannot be validated in this version, so it is refused rather than silently dropped.

The checkout create can also return commerce/checkout/offering-not-purchasable (422) — the offering resolved but has no usable price binding. The checkout create requires an Idempotency-Key request header of at least eight characters, and the only body keys it accepts are offering_ref, journey_id, and an optional promo. One more typed response comes from the enrollment status read rather than checkout:

`type`	`status`	What it means
`https://purple.md/problems/journey-status-pending`	`422`	Returned by `GET /v1/journeys/{journey_id}/status` when the platform has no status to report for an enrollment that is yours. Branch on this `type`: it means “no status yet”, not a missing enrollment and not a malformed call. The `detail` explains the situation at the time of the call; the `type` is the stable part. See when a status is not yet reportable.

That read can also return 503: the status source was unavailable, so the read did not succeed. That tells you nothing about the enrollment itself — retry with backoff, and do not read a failed call as a statement about the patient. Both sit alongside the 400/401/404 refusals above, not in place of them.

When a refusal is not namespaced

Not every refusal carries a namespaced type. Some the platform makes before it reaches the checkout logic — a request whose body is not valid JSON, or one missing its X-Brand-Id — come back with the RFC 7807 default type of about:blank, still carrying a title, the HTTP status, and a detail. So switch on type when it is namespaced, and fall back to the HTTP status when it is about:blank. The list above is the set of named types you will meet; treat it as the ones worth branching on, not as an exhaustive catalog of every possible refusal.

Reading a 404

Not every 404 means the same thing:

A 404 whose type is namespaced (commerce/…) means your call reached the platform and the resource is mounted but not configured — fix your configuration or your pricing, not your URL.
A 404 with the generic type https://purple.md/problems/not-found means the path itself is not a routable resource — check the URL and the /v1 prefix.

One ordering detail on the key-authenticated calls: a request with no key is refused 401 before the path is routed, so a wrong path sent without a key returns that 401 rather than the generic 404.

​Identifiers

​The enrollment thread

​Problem responses

​The API-key wall

​The typed responses you will meet

​When a refusal is not namespaced

​Reading a 404