Connect a Lovable storefront

Lovable generates a web app from a written prompt. That makes it a fast way to stand up a branded storefront in front of this platform — and it makes one mistake unusually easy, because a prompt is pasted whole and the generated code runs in your patient’s browser. This page is written for that: what your storefront owns, what the platform hosts, which credential may ever reach client code, how to confirm your first test order, and a prompt you can reuse. The examples use the brand id brd_acme and the offering SEMA-1M. Substitute your own brand id and offerings.

The site kit is not the Lovable path. The platform’s site kit is a separate Next.js starter that you fork and deploy yourself. If you are building in Lovable, ignore it: this page and the prompt below are your whole path. Do not mix the two.

Read this before you paste anything into a prompt. On this platform, an API key beginning pk_ is a server secret. That is the opposite of the convention some payment tools use, where a pk_ value is the browser-safe one. The browser-safe credential here begins pub_test_ or pub_live_.A pk_ value pasted into a Lovable prompt, a client component, or a public repository is a disclosed server credential and must be rotated — and rotation is bounded, not instant: the old value can still be accepted for up to 30 seconds afterwards. See your credentials.

Use only invented test patients whose names include the uppercase word TEST; test mode never charges a real card.

What your storefront owns, and what the platform provides

Your Lovable app owns	The platform provides
Brand, copy, imagery, merchandising layout	The price and the terms, resolved server-side from your configured catalog
Product browsing and the call-to-action	The hosted checkout page, including all card collection
Sending the patient to sign in	The sign-in page and the patient’s session
Post-purchase links back into the account	The clinical questionnaire, the clinician review, and the member portal

Your storefront never renders a card field, never holds a payment credential, and never creates a patient account. It presents a price, and hands the patient to a platform-hosted page with a link. The full contract for that hand-off is the checkout door — read it alongside this page; nothing here replaces it.

The four values, and where each may live

Credential	Looks like	May it appear in Lovable-generated client code?
API key	`pk_...`	Never. Server-side only.
Publishable brand key	`pub_test_...` / `pub_live_...`	Yes — that is what it is for.
Brand id	`brd_...`	Yes. It is an identifier, not a secret.
Webhook signing secret	`psig_...`	Never. Server-side only.

The publishable key is brand-scoped and read-only. It is issued by your onboarding contact, per brand, and shown once — the same handling as your API key, minus the secrecy. It reaches exactly two operations and is refused everywhere else, writes included:

GET /v1/account/brands/{brand_id}/storefront — one offering’s price and your brand’s readiness to sell it, in one call.
GET /v1/account/brands/{brand_id}/readiness — the readiness report on its own. Its brand-wide checks include your payment account and your checkout consent documents: payment stays locked until the consent documents are configured.

Everything else in this guide — starting a questionnaire, reading a payment status, reading an enrollment status, registering a webhook endpoint — needs the API key and therefore needs a server.

Permitted browser origins

A browser will not let your page read a cross-origin API response unless the platform grants it. The grant is a list of exact origins on your brand’s member domain row, and you manage it yourself. The same list decides where a questions-first hand-off may come from: the checkout door accepts a form POST only from an origin on it (see handing the patient to checkout).

# read the current list
curl "$PURPLE_API_BASE/v1/account/brands/brd_acme/domains/member/browser-origins" \
  --header "Authorization: Bearer $PURPLE_API_KEY" \
  --header "X-Brand-Id: brd_acme"

# replace the list (this is a replace, not a merge)
curl --request PUT "$PURPLE_API_BASE/v1/account/brands/brd_acme/domains/member/browser-origins" \
  --header "Authorization: Bearer $PURPLE_API_KEY" \
  --header "X-Brand-Id: brd_acme" \
  --header "Content-Type: application/json" \
  --data '{"browser_origins": ["https://my-storefront.example.com", "https://preview.example.com"]}'

Three properties that matter to a Lovable project specifically:

Exact origins only — a wildcard entry is refused. Scheme, host and port, nothing else. You cannot register a pattern that covers every preview URL Lovable hands you; register the specific origins you intend to use. The response returns the entries it refused, by name, so a typo tells you which one rather than presenting as “the browser read is broken”. Plain http is accepted only for a loopback host (localhost, 127.0.0.1, [::1]), so a local preview can use http://localhost:5173; every other origin must be https.
Each Lovable address is its own origin. The editor preview and the published app are served from different hosts, and each one you load the page from needs its own entry. Copy the origin from the address bar of the page that makes the call: the scheme and host, with no path.
It is a replace. Removing an origin from the array revokes it.
Your brand needs a member domain registered first. Without one there is no row to hold the list. See login URLs and domains.

Two switches, both yours to ask for. The browser read needs a publishable key issued for your brand and your page’s origin on the list above. Until both are in place every cross-origin call is refused, whatever credential it carries. Build against the server pattern below either way, and switch the read to the browser once you have both.Both operations declare either credential in the reference — your server key or your publishable key — so the interactive playground can exercise them with either one. The origin allowlist is what the playground cannot reproduce: test the cross-origin path from your own page.

The architecture to build against

Lovable projects commonly pair a generated frontend with a server function (its Supabase integration, or any backend you already run). Use that server side. It is not optional styling — it is where your API key has to live.

Lovable page  ──►  your server function  ──►  https://api.<env>.purplelabelmd.com/v1/...
 (no secrets)      (holds pk_… API key)        (price, questionnaire, status reads)
      │
      ├──────────►  member portal sign-in link  (a link — no API call, no credential)
      └──────────►  member portal checkout      (a link — no API call, no credential)

Development setup

The names below are the ones in your welcome kit.

Value	Where it comes from	Where it lives
`PURPLE_API_BASE` (`https://api.<env>.purplelabelmd.com`, no `/v1`)	Your welcome kit	Server environment variable
`PURPLE_API_KEY` (`pk_...`)	Onboarding contact, shown once	Server secret store
`PURPLE_BRAND_ID` (`brd_...`)	Your welcome kit	Either side
`PURPLE_SUPPORT_EMAIL`	Your welcome kit names it and leaves it for you to fill in: the support address your storefront shows	Either side
Publishable key (`pub_test_...`), optional	Onboarding contact, per brand, shown once	Client environment variable
Offerings: `offering_ref`, `sku_id`, and each offering’s exact checkout link	Your welcome kit	Either side
Member portal address (`MEMBER_HOST`)	Your welcome kit	Client — sign-in, checkout and the portal all live there
Entry mode, for each offering, and the setting that decided it	Your welcome kit	Decides which path below you build

The example offering on this page is offering_ref SEMA-1M, sku_id sku_b7945bba07e4, therapy weight_loss. Use your own. Everything on this site targets the test-mode environment with test-scoped keys and synthetic data only — see environments. An offering also needs product copy, a price, billing terms and your checkout consent documents before a patient can pay for it. The welcome kit lists those steps and the call that adopts the starter product copy: see before a price is payable.

Which way in: your entry mode

Your entry mode is set for your account when your program is set up, and a single offering can be set differently. Your link cannot change it.

Entry mode	Configuration name	What your storefront does
Questions-first	`clinical_before_pay`	Runs the health questions first, from your server, then hands the patient to checkout with a form POST that carries the one-time checkout pass the last answer returned. See Path A.
Checkout-first	`clinical_after_pay`	Links straight to checkout carrying `offering_ref`, `sku_id` and `therapy`. The questions come after payment, inside the member portal. See Path B.

Your welcome pack shows each offering’s entry mode, which setting decided it (set for this offering, the account’s setting, or the platform default when none is set), and the exact checkout link to build. Build the path the pack shows for each offering, not a path you assume. On a questions-first offering your storefront does not open the pack’s link itself: the checkout door sends the patient there after the form POST described in Path A. A checkout link that carries no journey_id never opens the payment form. The payment step stays locked, and the page tells the patient: “This deployment completes your health questions before payment, and this link carries no enrollment — start with your health questions and you’ll come back here with everything attached.” A patient who is not logged in sees the sign-in lock first. Your storefront never calls POST /v1/prospects: on a checkout-first offering the platform’s own hosted checkout makes that call on its server.

Signing the patient in

Your storefront may send the patient through your member portal’s sign-in link before checkout:

https://{MEMBER_HOST}/auth/login?returnTo=/home

This is the member portal’s own sign-in route, and it gives the patient a member portal session. The patient must have a member portal session before they pay: the order belongs to the account that is logged in to the portal at payment, and only that account’s portal shows it. (The checkout’s own sign-in step uses the same portal route, so a patient who arrives logged out signs in there before paying.) So signing in is required, and the checkout handles it itself: payment stays locked until the patient is logged in. Your storefront’s own sign-in step is optional. Your storefront cannot tell whether a patient already has a member portal session, because that session lives on the member portal address, not on yours, so show the sign-in link to everyone. Do not link patients to the API’s /v1/auth/login: it returns to the API host and does not sign the patient in to the member portal (see login URLs and domains).

Path A — questions first

Every call on this path is a server call. Your page can render questions and collect answers, but it can never talk to these endpoints itself. Plan the backend before you plan the pages. The questionnaire is served one question at a time, by the server, which owns sequence, branching and completion. See how questions work for the model.

# 1. start a session for the product the patient chose. The FIRST resolve mints the enrollment:
#    the response carries session_id, journey_id and the first node. A brand with more than one
#    treatment refuses a start without `offering` (422).
curl "$PURPLE_API_BASE/v1/instrument/resolve?offering=SEMA-1M" \
  --header "Authorization: Bearer $PURPLE_API_KEY" \
  --header "X-Brand-Id: brd_acme"

# 2. submit the current node's answer, KEYED to the node you served
curl --request POST "$PURPLE_API_BASE/v1/instrument/next" \
  --header "Authorization: Bearer $PURPLE_API_KEY" \
  --header "X-Brand-Id: brd_acme" \
  --header "Content-Type: application/json" \
  --data '{"session_id": "<from step 1>", "node_id": "<the served node.node_id>", "answer": {"codes": ["none"]}}'

Always send node_id. It keys the answer to the node it was collected for. With it, a stale replay of an already-passed node resyncs cleanly — 200, current node re-served — and a submit for a node the session has not reached fails closed with a renderer.node_mismatch issue (422). Without it, an answer can misbind to whatever node follows a server-side skip, on a path that carries a patient’s health answers. The codes answer above is for a choice control. Text, email, number, date and phone controls send {"value": ...} instead, and a number pair, an address and a file capture each take their own shape — every control and its answer is listed in controls and their answers. Repeat step 2 while status is active, and stop when it is complete, blocked or abandoned.

Handing the patient to checkout

A checkout link carrying journey_id cannot complete checkout on this path. Naming an enrollment does not prove it is this patient’s, so the checkout refuses it. What proves it is a one-time checkout pass that the platform gives your server when the questions are complete. 1. Read destination_capability from the completing response. The POST /v1/instrument/next response whose answer completes the questionnaire (status is complete) carries a destination_capability string. It is there only when all of these hold:

that call is the one that completed the questionnaire. A later call of yours on a session that is already complete returns no pass (if the platform has to redeliver the completion internally, the pass it returns is minted fresh for the same enrollment, never a stored copy served again);
your server started the session itself, with your secret API key, as a fresh start: no X-Journey-Id header, so the first resolve created the enrollment;
the questionnaire was served in one pass, with no phase. Phase-split questionnaires are not yet available on this path (see splitting the questionnaire).

The value is a credential. Keep it on your server. Never put it in a URL or a log, and never return it to your page’s JavaScript as data. If the completing response does not carry it, this enrollment cannot be handed to checkout: start a new questionnaire. 2. Send the patient to the checkout door with a top-level form POST. When the questions complete, navigate the browser to a route on your server, with a full page load rather than a fetch. That route returns a page holding a form that posts to your member portal’s checkout door. The pass goes in the request body, in the capability field, with your offering_ref beside it:

<!doctype html>
<html>
  <body>
    <form id="door" method="post" action="https://{MEMBER_HOST}/api/checkout/door">
      <input type="hidden" name="capability" value="{destination_capability}">
      <input type="hidden" name="offering_ref" value="SEMA-1M">
      <button type="submit">Continue to checkout</button>
    </form>
    <script>document.getElementById('door').submit();</script>
  </body>
</html>

The script submits the form as soon as the page loads, and the button covers a browser that runs no script. The form carries no journey_id: the door reads the enrollment from the pass itself. Do not replace the form with fetch or a link. The door accepts only a POST whose body is a form (application/x-www-form-urlencoded or multipart/form-data), and a GET is refused.

Not yet verified on Lovable hosting. This step assumes your server function can do two things: return the HTML page above as a full page, and keep the pass on the server for this visitor (for example, behind an httpOnly cookie on that host). Neither has been tested on Lovable’s hosting yet. The door’s side of the hand-off is unaffected. Confirm both in your own project before you rely on this pattern.

3. Post from a registered origin. The door accepts the POST only when the browser’s Origin header exactly equals one of your brand’s registered browser origins, which is the same list described under permitted browser origins. This applies on Path A even if you never use a publishable key. The Origin the browser sends is the origin of the page that holds the form. Register every address a patient can finish the questions from: your published storefront and each named preview or editor host you test from. If the form page is served by a server function on a different host from your storefront, register that host’s origin. A missing, null or unlisted origin is refused. 4. The 10-minute window. The pass lasts about 10 minutes from the answer that completed the questions. The door checks it, and so does the checkout when the patient submits their details, so the hand-off, any sign-in and the checkout submission all have to happen inside that window. Hand off as soon as the questions complete. An expired pass is never reissued from the enrollment id. If the window lapses, the patient starts the questionnaire again from your storefront: a fresh resolve with no X-Journey-Id, which creates a new enrollment, and whose completion carries a new pass. What the patient sees:

Accepted. The door sends the patient straight to your hosted checkout, wearing your brand, for the offering you posted. A patient who is not logged in signs in there first. Payment then works as on any other offering.
Refused at the door. An expired, missing or malformed pass, a pass for another brand, a GET, or an unlisted origin all get the same plain not-found response from your member portal address. It is not a branded page and it does not say which check failed. Nothing is created and nothing is charged.
Window lapsed after the door. If the patient reaches checkout but submits after the pass has expired, the checkout shows “We couldn’t confirm this enrollment — nothing was charged.” and nothing is charged. On this path the way back is your storefront’s questionnaire, started again.
The platform could not check the pass. The door answers that the service is unavailable, sets nothing and charges nothing.

Splitting the questionnaire around the payment

GET /v1/instrument/resolve takes an optional phase parameter that serves one tier of the questionnaire on its own:

`phase`	What it serves
`qualification`	The pre-payment tier. It completes at the qualification end point, and the enrollment then hands to checkout.
`clinical`	The post-payment tier, re-opened by the same enrollment id after checkout.
omitted	The whole questionnaire in one pass, one end point. This is the default and is unchanged.

curl "$PURPLE_API_BASE/v1/instrument/resolve?phase=qualification&offering=SEMA-1M" \
  --header "Authorization: Bearer $PURPLE_API_KEY" \
  --header "X-Brand-Id: brd_acme"

Serving a phase requires a questionnaire configured in tiers; an unknown value is rejected with 400. Whether your brand can serve a phase therefore depends on its questionnaire configuration — confirm that with your onboarding contact before you design a page around the split. Not yet available: a phase-split questionnaire cannot reach checkout yet. It will once the platform issues the checkout pass at the qualification completion, the last step before checkout. That change is being built, and this page and the changelog will say when it ships. Until then a phase=qualification completion carries no destination_capability, so for a questions-first checkout, serve the whole questionnaire in one pass. Four constraints to design around:

Server-side only. These operations need the API key, they carry patient answers, and they are not on the browser-safe list — a Lovable page cannot call them directly, with any credential. Proxy them through your server function and never return more to the page than the question to render.
Resume is a header, and a resumed questionnaire cannot reach checkout. Send the enrollment id back as X-Journey-Id to continue a questionnaire on a return visit. A session resumed that way completes without a destination_capability, because naming an enrollment does not prove it is this patient’s. To take that patient to checkout, start a new questionnaire.
Which questionnaire is served follows your brand’s configured therapies. A brand with more than one enabled therapy must name an offering on the entry link so the therapy is unambiguous.
Proof-of-identity capture is never part of this questionnaire. Questions collecting a government ID are withheld here and are not counted toward completion; the patient verifies identity in the member portal’s own identity step. See the identity handoff.

Path B — checkout first (only where you are configured for it)

This path needs no server of your own for the hand-off, but it works only on a checkout-first offering. On a questions-first offering, this link keeps the payment step locked and sends the patient to the health questions first, as described above.

Present the offering. Read the price on your server with your API key and pass it to the page, or read it in the browser with your publishable key once your origins are registered. Either way send X-Brand-Id — it is required, and with a publishable key it must equal the brand that key was minted for, or the read answers 404. Key the buy control on price_status, which every successful (200) storefront read carries: available or pending. When it is available, the read carries list_price: that amount_minor is the amount the checkout charges, and the one to show. pending means a price is set but the billing terms are not, or the catalog was briefly unavailable, or the offering’s copy is written but its price is not set yet: show no amount and no buy control. Whenever the offering’s copy has been written, the read carries it in copy (display_name, description, includes), whatever the price state, so the page can show the offering’s words while its price is pending. An offering with neither copy nor a price does not answer 200: the read answers 404 with type commerce/merchandising/not-configured. The prices list is display only (compare-at and introductory amounts). It may be empty, and it never sets what the patient is charged. The readiness block, including each offering’s activation status, is information for you. Do not show or hide the buy control on it.
Optionally, sign the patient in with the sign-in link above. The checkout signs the patient in itself if you do not.
Hand off with a link. Send the patient to /checkout on your member portal address, carrying the offering:
https://{MEMBER_HOST}/checkout?offering_ref=SEMA-1M&sku_id=sku_b7945bba07e4&therapy=weight_loss
The parameters select what to present, never what anything costs. A link cannot name a price, a discount or a fee. A checkout-first link needs all three, and they must be one offering’s values exactly as your welcome pack and onboarding contact give them. Never mix the sku_id or therapy of one offering with the offering_ref of another.
The patient pays on the hosted page. Card details travel from the patient’s browser to the payment provider. Nothing payment-shaped passes through your code.
The patient continues inside the portal — to the clinical questionnaire, then to their plan. There is no redirect back to your storefront, so your storefront is not where the outcome arrives. See below.

What you own on this path, and where it ends. The storefront, the hand-off link and the reads your server makes afterwards are yours to build now. Everything from the checkout page onward — the payment, the questionnaire the patient meets next, the clinician review — is served by the platform inside the portal, and its content is configuration for your program rather than something your storefront drives. Confirm what your brand’s post-payment questionnaire currently serves before you write copy or a progress indicator that depends on its shape.

Never infer payment from the browser

There is no redirect back to your storefront after payment, and the outcome never rides the patient’s browser to reach you. A page that concludes “paid” because the patient returned, or because a timer elapsed, is guessing. Read the authoritative status from your server instead:

GET /v1/payments/{order_ref}/status — the order’s own payment_state. Fed by confirmed events from the payment provider, never by guesswork. Branch on the wire values exactly as the reference declares them — created, payment_authorized, paid, payment_failed, partially_refunded, refunded, disputed, cancelled. Prose names like “authorized” or “failed” are not what the field carries, and a storefront matching on those never matches.
POST /v1/webhooks/registrations — register an endpoint and the response returns your signing secret once. Deliveries carry an event type and identifiers only, so a delivery prompts a read rather than carrying detail.
GET /v1/journeys/{journey_id}/status — the patient-visible enrollment status, for your own progress copy. It never carries payment detail, and it may answer with a typed no status yet instead of a status value.

A failed payment still leaves a readable order — the attempt is never invisible.

Confirm your first test order

A test order is working when both of these hold:

The order is on the patient’s order page. Logged in as the test patient, open https://{MEMBER_HOST}/order. The order is listed there. On a test brand whose clinical hand-off is not connected yet, the order reads “On hold on our side”. That is expected, and it still shows the order reached the portal.
Your server reads the order’s payment state. Take the order reference from the order’s row on that page (each row shows it). No webhook delivery carries the order reference. GET /v1/payments/{order_ref}/status answers with a payment_state. An order on hold may read payment_authorized: the card is authorized but not yet charged. You do not need paid to confirm a test order.

The event journey.payment.succeeded.v1 is not proof of a charge. It is not emitted from a confirmed payment, so do not use it to decide that a patient has paid.

States your page must have

A generated app will happily render a price of undefined. Ask for these explicitly.

State	What the patient should see
Price loading	A skeleton, not a zero and not a stale amount.
`price_status` is `pending`	The offering, without an amount, and no buy control.
`404` `commerce/merchandising/not-configured`	The offering has no copy and no price yet. Leave it off the page.
Enrollment status unavailable	That the status cannot be read right now — never an inferred “progressing” or “complete”. A missing status is not evidence of movement. Re-read with bounded backoff.
`401` from your server function	Your server’s credential problem, never the patient’s. Show a neutral error; log the outcome, not the credential.
`404` on a brand or offering	Check the brand id and offering reference. The platform answers `404` for a brand you do not own rather than revealing that it exists.
Retry	Bounded backoff on reads. Never auto-retry a checkout hand-off in a way that could open a second session.

The reusable prompt

Paste this into Lovable and fill the bracketed values. It contains no credentials and instructs the generated app never to hold one. It is written for questions-first mode; the checkout-first variant is marked.

Build a single-product storefront for a telehealth brand.

ARCHITECTURE
- A public marketing/product page plus server functions. The browser never holds a server secret.
- The server functions read two environment variables: PURPLE_API_BASE and PURPLE_API_KEY.
  PURPLE_API_BASE is an origin like https://api.<env>.purplelabelmd.com, with no /v1; every
  path below writes /v1 itself.
  PURPLE_API_KEY starts with "pk_" and is a SERVER SECRET. Never reference it in client code,
  never inline it, never log it, never expose it through a public route.
- The client may use only: PURPLE_BRAND_ID (starts with "brd_"), PURPLE_SUPPORT_EMAIL (the
  support address the page shows) and, if provided, the publishable brand key (starts with
  "pub_test_" or "pub_live_"). All three are safe in the browser.

SERVER FUNCTION: GET /api/offering
- Calls: GET {PURPLE_API_BASE}/v1/account/brands/{PURPLE_BRAND_ID}/storefront?offering_ref={OFFERING_REF}
- Headers: Authorization: Bearer {PURPLE_API_KEY}, X-Brand-Id: {PURPLE_BRAND_ID}
- Returns to the page only: price_status, pricing.copy (display_name, description, includes) when
  present, and pricing.list_price (amount_minor and currency) when price_status is "available".
  Never forward the raw upstream response and never forward headers.
  The pricing.prices list is display only and never the amount charged.

SERVER FUNCTIONS: the health questions (questions-first mode)
- POST /api/questions/start calls GET {PURPLE_API_BASE}/v1/instrument/resolve?offering={OFFERING_REF}
  and POST /api/questions/answer calls POST {PURPLE_API_BASE}/v1/instrument/next with
  session_id, node_id (the served node's node_id) and the answer. Same two headers as above.
- Return to the page only the node to render, the status and any issues. Stop when status is
  complete, blocked or abandoned. Always start fresh (no X-Journey-Id): only a fresh start can
  reach checkout.
- When the answer call returns status "complete", its response carries destination_capability, a
  one-time checkout pass that lasts about 10 minutes. It is a CREDENTIAL: keep it on the server,
  tied to this visitor by an httpOnly cookie on this site. Never return it to the page as data,
  never put it in a URL, never log it.

SERVER FUNCTION: GET /api/continue-to-checkout (questions-first mode)
- NOT YET VERIFIED ON LOVABLE HOSTING: serving this HTML page and keeping the pass per visitor
  have not been tested there. Confirm both work in this project before relying on them.
- Opened by a full page navigation, not a fetch, as soon as the questions complete.
- Returns an HTML page holding a form, method "post", action
  https://{MEMBER_HOST}/api/checkout/door, with two hidden fields: capability (the stored
  destination_capability) and offering_ref ({OFFERING_REF}). The page submits the form on load and
  also shows a "Continue to checkout" submit button. Delete the stored value once the page is served.
- If there is no stored value, or it is older than 10 minutes, do not render the form: send the
  patient back to start the health questions again.
- The address this page is served from must be one of the brand's registered browser origins.

SIGN IN
- A "Sign in" link goes to https://{MEMBER_HOST}/auth/login?returnTo=/home
- The Sign in link is optional: the hosted checkout signs the patient in itself before payment.
- Do not build a password form. The platform hosts sign-in.

PRODUCT PAGE
- Fetches /api/offering on load. Three render states: loading (skeleton), price_status "pending"
  (show the offering with no amount and no buy control), and price_status "available" (show the
  list_price amount and the buy control).
- Show or hide the buy control on price_status only. Do not hide the product.
- The buy control starts the health questions. When they complete, navigate the whole page to
  /api/continue-to-checkout. Never build a checkout link with journey_id in it: checkout refuses it.
  (Checkout-first mode only: skip the questions and link to
  https://{MEMBER_HOST}/checkout?offering_ref={OFFERING_REF}&sku_id={SKU_ID}&therapy={THERAPY})
  Open it in the same tab. Do not collect any payment detail. Do not render a card field.

AFTER CHECKOUT
- There is no redirect back to this site and no payment result in the browser. Do not add a
  "thank you" page that claims a payment succeeded, and do not poll any browser value for it.
- Add a "Manage your plan" link to https://{MEMBER_HOST}/home for returning patients.

RULES
- No promo code field or discount copy of your own: promo codes are not supported yet; the field
  is reserved. The hosted checkout shows a promo field, and it refuses every code with "Promo
  codes aren't available yet. Remove the code to continue."
- No secret in client code, in any prompt, or in the repository. No card field. No patient health
  information stored in this app. No analytics event carrying an identifier from the API.
- Every network failure gets a visible, plain-language state. Never render "undefined" or "NaN".

FILL IN: OFFERING_REF and MEMBER_HOST, from the checkout link your welcome pack issues for the
offering. Questions-first mode needs nothing else in the prompt, but the address that serves
/api/continue-to-checkout must be registered as one of the brand's browser origins before the hand-off
works. Checkout-first mode only: also fill SKU_ID and THERAPY, copied from that offering's
checkout-first link in your welcome pack.

Development walkthrough checklist

Read each offering’s entry mode and checkout link from your welcome pack.
Store the API key in your server environment. Confirm it appears in no client bundle.
Read the offering on your server and confirm price_status renders, with the amount when it is available.
Sign in through https://{MEMBER_HOST}/auth/login?returnTo=/home and confirm you land in the member portal wearing your brand.
Build the hand-off for your entry mode and confirm it opens the hosted page wearing your brand. Checkout-first: the checkout link. Questions-first: register the origin your form page is served from, finish the questions, and confirm the form POST to the checkout door lands on the checkout within the 10-minute window.
Place a test order as a logged-in, invented, TEST-named patient, and confirm it the way Confirm your first test order describes: the order on the portal’s order page, and its payment_state read by your server, not the browser.
Only then, if you want the browser read: register your origins, ask for your publishable key, and move the price read client-side.

Common integration errors

Symptom	Cause
The browser blocks the price read	Your origin is not registered, or no origin is registered at all. Register exact origins on the member domain row.
`401` on every call	The key is missing or revoked. The body is deliberately opaque — it never says which, and never reveals whether a key exists.
`400` with type `https://purple.md/problems/malformed-brand`	The key was accepted but `X-Brand-Id` is missing or is not a well-formed `brd_` id. This is a different wall from the `401`, and it is checked before your request is dispatched.
`404` for a brand you believe exists	The brand is not one of yours. Existence is never revealed across accounts.
`404` with the generic not-found type	The path is wrong. Check that the path starts with `/v1` and that `PURPLE_API_BASE` does not also end in `/v1`.
The checkout keeps payment locked and asks the patient to start with their health questions	This offering is questions-first. Run the questions first and hand the patient over with the form POST to the checkout door. A link carrying `journey_id` is not enough.
The checkout says “This buy link is incomplete (missing its product context), so your enrollment can’t be started from it — nothing was created.”	A checkout-first link is missing `sku_id` or `therapy`. Carry all three values (`offering_ref`, `sku_id`, `therapy`) of one offering, exactly as your welcome kit gives them.
The checkout door answers a plain not found	The pass expired (about 10 minutes), the form page’s origin is not registered exactly, the form was sent as a `GET` or a link, or the `capability` field is missing. The door does not say which. Check the origin first, then start the questions again for a fresh pass.
The questions complete but the response has no `destination_capability`	The session was resumed with `X-Journey-Id`, your call came after the session was already complete, or the platform could not issue the pass in time: start a fresh questionnaire with no `X-Journey-Id`. Or the session was served with `phase=qualification`: not yet available, because phase-split questionnaires reach checkout only once the platform issues the pass at the qualification completion, which is being built. Serve the whole questionnaire in one pass.
The checkout says “We couldn’t confirm this enrollment — nothing was charged.”	The pass expired before the patient submitted checkout. Start the questions again from your storefront.
The patient logged in, but the portal does not know them	The sign-in link went to the API’s `/v1/auth/login`. Use the member portal’s own `/auth/login` on your member portal address.
The order is not on the patient’s order page	You are looking at a different account: the order belongs to the account that was logged in to the member portal at payment.
The price shows as `pending` forever	A price is set but the offering’s billing terms are not. See before a price is payable.
`404` with type `commerce/merchandising/not-configured` on the storefront read	The offering has neither copy nor a price for your brand. See pricing.
A second charge after a retry	Do not retry the hand-off blindly. The hosted page creates its session under an idempotency key; your storefront should not create a second entry.

Before you rely on any of this

Five things to confirm for your brand before you plan a launch around this page. None of them are code you write — they are configuration and credentials, and your onboarding contact owns them.

Your entry mode, for each offering, as your welcome pack shows it. On a questions-first offering, a link that carries no enrollment keeps the payment step locked.
Your member portal address is set up. Without it there is no sign-in link and no checkout.
Whether your publishable key is issued and your browser origins are registered. Until both are in place, the two browser reads are unavailable to your page and the server pattern above is your only route to a price. On a questions-first offering the origins matter even without a publishable key: the checkout door refuses a hand-off from an origin that is not registered.
Whether your brand’s questionnaire is configured in tiers, if you want the split entry with phase. Without tiers there is no qualification tier to serve on its own.
What your brand’s post-payment questionnaire currently serves. The platform owns that content; confirm its current shape before you design copy or a progress indicator around it.

And two standing facts about this site’s environment: every example runs in test mode — no real card is ever charged, and you use only invented test patients whose names include the uppercase word TEST (see the warning at the top and Environments) — and the prompt above is a starting point to verify in your own project, not a certified integration. Run your own flow before you ship one.

​What your storefront owns, and what the platform provides

​The four values, and where each may live

​Permitted browser origins

​The architecture to build against

​Development setup

​Which way in: your entry mode

​Signing the patient in

​Path A — questions first

​Handing the patient to checkout

​Splitting the questionnaire around the payment

​Path B — checkout first (only where you are configured for it)

​Never infer payment from the browser

​Confirm your first test order

​States your page must have

​The reusable prompt

​Development walkthrough checklist

​Common integration errors

​Before you rely on any of this

What your storefront owns, and what the platform provides

The four values, and where each may live

Permitted browser origins

The architecture to build against

Development setup

Which way in: your entry mode

Signing the patient in

Path A — questions first

Handing the patient to checkout

Splitting the questionnaire around the payment

Path B — checkout first (only where you are configured for it)

Never infer payment from the browser

Confirm your first test order

States your page must have

The reusable prompt

Development walkthrough checklist

Common integration errors

Before you rely on any of this