# FrontDesk Storefront API

Run your own website or app on a FrontDesk merchant's data: their catalogue, events,
forms and checkout. You build the frontend; FrontDesk stays the source of truth and
handles the money.

Base URL: https://api.frontdesk.africa/v1

Building with an AI app builder (Lovable, v0, Bolt)? Paste https://api.frontdesk.africa/v1/store/lovable.txt
into it first: it describes the architecture to generate, not just the endpoints.

## Credentials

Two kinds, and the difference matters:

- `fd_pk_…` PUBLISHABLE. Reads, plus one write: registering a guest for a FREE event.
  SAFE to ship in browser code. It is locked to the exact origins the merchant
  registered, so it only works from their own site.
  An empty origin list REFUSES every call. That is deliberate, not a bug.
- `fd_sk_…` SECRET. Can open checkouts. SERVER ONLY. Never put it in a page: anyone
  viewing source can then take payments as that merchant.

Keys are per workspace and carry the environment: `fd_pk_test_…` works against staging,
`fd_pk_live_…` against production. A key from the wrong environment is refused.

You never choose which workspace you are reading: the key decides. Any workspace ref you
send is ignored.

## Responses

Success returns the resource itself. Errors are:

    { "error": { "code": "...", "message": "...", "retryable": bool, "requestId": "..." } }

`code` is stable and safe to branch on. Quote `requestId` when asking for help.
Common codes: UNAUTHORIZED, ORIGIN_NOT_ALLOWED, INSUFFICIENT_SCOPE, STORE_API_DISABLED,
STORE_API_SECRET_DISABLED, KEY_PAUSED (the merchant paused this key), NOT_FOUND,
VALIDATION_ERROR, RATE_LIMITED (429, honour
Retry-After), INTERNAL.

Publishable keys work as soon as you create one and list an origin. STORE_API_SECRET_DISABLED
means the merchant has not switched secret keys on. They can do that themselves in their
FrontDesk portal, under Developers. STORE_API_DISABLED means the whole workspace is off.

## Endpoints

### GET /v1/store/storefront
The whole storefront: brand, theme, sections, pages, and the embedded event, collection and product lists.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: storefront:read (the umbrella scopes read/transact also satisfy it)
Returns: Storefront
NOTE: One call is enough to render a home page. Events, collections and products also ride inside this, so you can render everything from one response.

### GET /v1/store/products
Every public product, as summaries.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: products:read (the umbrella scopes read/transact also satisfy it)
- updatedSince (query): ISO 8601. Only products changed at or after this moment, ordered oldest change first — for keeping a local copy fresh. Feed the largest updatedAt you received back as the next cursor; the >= comparison re-sends the boundary row, so upsert by ref.
- limit (query): Page size for delta reads, max 200. Without updatedSince the list is the storefront display order, unpaged.
Returns: PublicProductSummary[]
NOTE: Delta reads only see PUBLIC products: a product that was deleted arrives as the product.deleted webhook instead, and one that was merely unpublished simply stops appearing — reconcile against the full list occasionally if you keep a mirror.

### GET /v1/store/products/:slug
One product with its variants, media, specs and description blocks.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: products:read (the umbrella scopes read/transact also satisfy it)
- slug (path, required): The product's slug.
Returns: PublicProduct
NOTE: When `options` is present the product sells along several axes (Size × Colour): render one picker per group and resolve the buyer's picks to the variant whose `optionValueRefs` holds exactly those value refs. Checkout still takes that variant's ref.

### GET /v1/store/products/:slug/slots
Bookable slots for a product that is scheduled rather than shipped.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: availability:read (the umbrella scopes read/transact also satisfy it)
- slug (path, required): The product's slug.
Returns: PublicProductSlots

### GET /v1/store/collections
Every public collection, as summaries.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: products:read (the umbrella scopes read/transact also satisfy it)
Returns: PublicCollectionSummary[]

### GET /v1/store/collections/:slug
One collection with its products.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: products:read (the umbrella scopes read/transact also satisfy it)
- slug (path, required): The collection's slug.
Returns: PublicCollectionDetail

### GET /v1/store/events
Every public event, as summaries.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: products:read (the umbrella scopes read/transact also satisfy it)
Returns: PublicEventSummary[]
NOTE: Same list that rides inside /v1/store/storefront. Use this when you only need the events.

### GET /v1/store/events/:slug
One event with its ticket types, days and location.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: products:read (the umbrella scopes read/transact also satisfy it)
- slug (path, required): The event's slug.
Returns: PublicEvent

### GET /v1/store/forms/:slug
A published form and its field schema, so you can render it yourself.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: storefront:read (the umbrella scopes read/transact also satisfy it)
- slug (path, required): The form's slug.
Returns: PublicForm

### GET /v1/store/tables/:slug
A published data table: its columns and rows.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: storefront:read (the umbrella scopes read/transact also satisfy it)
- slug (path, required): The table's slug.
Returns: PublicTable

### GET /v1/store/catalogs/:slug
A public media catalog (a gallery).
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: storefront:read (the umbrella scopes read/transact also satisfy it)
- slug (path, required): The catalog's slug.
Returns: PublicCatalog

### GET /v1/store/files/:slug
A public file folder and its files.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: storefront:read (the umbrella scopes read/transact also satisfy it)
- slug (path, required): The folder's slug.
Returns: PublicFolder

### GET /v1/store/notes/:slug
A published note or document.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: storefront:read (the umbrella scopes read/transact also satisfy it)
- slug (path, required): The note's slug.
Returns: PublicNote

### GET /v1/store/delivery-zones
Delivery zones and their fees, so a cart can quote shipping before checkout.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: availability:read (the umbrella scopes read/transact also satisfy it)
Returns: DeliveryZone[]

### GET /v1/store/availability
Live stock and slot availability.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: availability:read (the umbrella scopes read/transact also satisfy it)
- variantRefs (query, required): Comma-separated variant refs your cart holds (max 100). A ref missing from the response map is no longer purchasable, so drop that line.
Returns: PublicStoreAvailability
NOTE: A cart lives in the buyer's storage, so its lines can be days old. Call this when the buyer returns: `variants` maps each ref to units left (null = untracked, no cap), and refs listed in `preorderable` are still buyable at 0 stock — cap those on `preorderRemaining` instead of dropping them.

### POST /v1/store/checkouts
Open a hosted checkout. Returns a URL to send the buyer to; you never handle payment.
Auth: Authorization: Bearer fd_sk_… (secret, server only)
Scope: checkout:create (the umbrella scopes read/transact also satisfy it)
Body:
- items (required): Array of { variantRef, quantity }. Every variantRef must resolve to a live product in this store; refs come from GET /v1/store/products.
- returnUrl (required): Where the buyer lands after paying. https, or localhost while testing.
- contact: Prefills the hosted page. The buyer can still correct it.
- currency: The currency the buyer pays in. Must be one the store accepts, and every item must carry a price in it (see prices[] on GET /v1/store/products); otherwise 400 VALIDATION_ERROR with `details.accepted` or `details.unpriced`. Omit for the store primary. Fixed for the life of the session: the hosted page, the order and the payment are all in it, and nothing falls back to the store primary.
- deliveryZoneRef: Required when any line needs delivery. The zone fee is charged in the checkout currency.
Returns: StoreCheckoutSessionView
NOTE: Requires an Idempotency-Key header. A retry then returns the SAME session instead of giving the buyer two carts. Items are validated here: an unknown or unpublished variantRef returns 400 VALIDATION_ERROR with the bad refs in `details.invalid`, and a variant with no price in the requested currency returns 400 VALIDATION_ERROR with the refs in `details.unpriced`, so both fail on your server rather than in front of your buyer. Pricing still happens when the buyer pays, in the session currency. Only rails that can charge that currency are offered on the hosted page (NGN: card, bank transfer; anything else: international card). A buyer who backs out of a payment returns to the hosted page, never to your returnUrl: only a paid checkout reaches returnUrl. A retry there pays the same order rather than opening another, and reopening hostedUrl resumes it, including a bank transfer already started. There is no `provider` field: the buyer picks how to pay on our page, which is why you never touch card data.

### POST /v1/store/events/:slug/checkout
Open a hosted checkout for event tickets.
Auth: Authorization: Bearer fd_sk_… (secret, server only)
Scope: checkout:create (the umbrella scopes read/transact also satisfy it)
- slug (path, required): The event's slug.
Body:
- tickets (required): Ticket lines: ticketTypeRef, quantity, optional amountMinor for donation tiers, and attendees to issue seats to named guests. attendees is POSITIONAL and its length must be quantity x groupSize: leave an entry blank to keep that seat under the buyer, never drop it, or the following names shift onto the wrong seats.
- products: NOT SUPPORTED YET: sending a non-empty array returns 400. Sell merchandise with a separate POST /v1/store/checkouts.
- contact (required): Buyer name, email and optional phone. The email receives the tickets.
- dateOfBirth: Buyer DOB as YYYY-MM-DD. Required when a chosen tier sets minAge and the event dobMode is order.
- responses: Answers to the questions on the chosen tiers, keyed by the field key. Required whenever one of those fields is required.
- discountCode: Promo code. Re-validated server-side.
- unlockCodes: Codes that reveal hidden or invite-only tiers. Re-verified server-side, and REQUIRED here for such a tier: without the code the tier is not on sale and the request is refused.
- promoterCode: Affiliate code from a share link. Ignored if unknown.
- currency: Must be a currency the event sells in. Omit for its primary.
- returnUrl (required): Where the buyer lands after paying.
Returns: StoreCheckoutSessionView
NOTE: Send Idempotency-Key: a retry returns the SAME checkout instead of two. Tiers are validated here, like product variants: a ref that is unknown, hidden without its unlockCode, sold out, or asked for outside its minPerOrder/maxPerOrder returns 400 VALIDATION_ERROR with the refs in details.invalid, details.soldOut or details.quantity, so the failure lands on your server and never on your buyer. You collect what the organiser asks for, and GET /v1/store/events/:slug tells you what that is: each tier carries formFields, requiresAttendeeDetails, groupSize and minPerOrder/maxPerOrder, and the event carries minAge and dobMode. Everything you send is re-validated here, so prices, availability and age limits are decided by the server, not by your form. Three of those rules REFUSE the order rather than warn, so collect them before you send: a required field left unanswered returns 400 "Please answer: <label>"; a tier with requiresAttendeeDetails returns 400 "Enter a name for each \"<tier>\" ticket" unless every seat carries a name; and an age-gated tier fails the age check without a date of birth, on the buyer when dobMode is order and on each attendee when it is attendee. Our own hosted checkout collects all three for you, and lets the buyer name each guest even when the tier does not demand it, so this only applies when you build your own form.

### POST /v1/store/events/:slug/register
Register a guest for a FREE event tier from your own page. FrontDesk sends the confirmation, the calendar invite and the ticket.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: events:register (the umbrella scopes read/transact also satisfy it)
- slug (path, required): The event's slug.
Body:
- tickets (required): Same shape as checkout: ticketTypeRef, quantity, and optional attendees to name each seat. attendees is POSITIONAL and its length must be quantity x groupSize: leave an entry blank ({}) to keep that seat under the registrant, never drop it. Every tier must be free.
- contact (required): The registrant: name, and an email and/or phone. The email receives the confirmation, the .ics invite and the ticket PDF; a phone-only guest gets an SMS.
- dateOfBirth: YYYY-MM-DD. Required when a chosen tier sets minAge and the event dobMode is order; per attendee when it is attendee.
- responses: Answers to the chosen tiers' questions, keyed by each formFields[].key from GET /v1/store/events/:slug. Required whenever one of those fields is required.
- unlockCodes: Codes that reveal hidden or invite-only tiers. Required for such a tier.
- promoterCode: Affiliate code from a share link. Ignored if unknown.
Returns: StoreEventRegistrationView
NOTE: The one write a publishable key may make, so call it straight from the browser, from an origin registered on the key. FREE tiers only: a paid, donation or deposit tier answers 402 TIER_REQUIRES_PAYMENT, and that is your cue to open POST /v1/store/events/:slug/checkout from your server instead. Every rule the hosted storefront applies runs here too: an unknown, hidden-without-its-code, or not-yet-on-sale tier is refused, capacity answers 409 TIER_SOLD_OUT, minPerOrder/maxPerOrder are enforced, a required question left unanswered returns 400 "Please answer: <label>", a tier with requiresAttendeeDetails needs a name on every seat, and an age gate needs the date of birth. Duplicates are quiet: when the email already holds a seat on this event you get the SAME 201 as a first registration (their existing reference and status), the confirmation is re-sent at most once every 10 minutes, and no new seat is issued, so a retry is always safe when an email is given and no Idempotency-Key is needed. A test key runs every one of those checks and answers test:true with a test_ reference, writing nothing and sending nothing. There is no read-back endpoint: subscribe to the attendee.registered webhook, and the organiser sees every guest in their portal.

### GET /v1/store/payment-methods
The payment rails this workspace can charge, so you can render your own picker.
Auth: Authorization: Bearer fd_pk_… (publishable, safe in browser code)
Scope: availability:read (the umbrella scopes read/transact also satisfy it)
- currency (query): Defaults to the store primary.
Returns: string[]

### POST /v1/store/events/:slug/checkout/headless
Open a ticket checkout you render yourself, including the payment step.
Auth: Authorization: Bearer fd_sk_… (secret, server only)
Scope: checkout:create (the umbrella scopes read/transact also satisfy it)
- slug (path, required): The event's slug.
Body:
- provider (required): The rail to use, from GET /v1/store/payment-methods.
- tickets (required): Ticket lines: ticketTypeRef, quantity, optional amountMinor for donation tiers.
- contact (required): Buyer name, email and optional phone.
- pricing: Your computed totalMinor. We re-price and return PRICE_MISMATCH if it disagrees.
- returnUrl (required): Your own page, where the buyer lands after paying. Must be https, or localhost while you build.
Returns: StoreHeadlessCheckoutView
NOTE: Seats are held until expiresAt. Name ONE rail: minting every rail at once would leave several live payment paths on one order, and a buyer could pay twice. Branch on the provider you asked for, never on which payment field is filled in: Paystack returns an accessCode AND a checkoutUrl, so code that redirects whenever checkoutUrl is present sends every card buyer to a Paystack page and never opens the popup. Paystack returns an accessCode for its inline popup: load js.paystack.co/v2/inline.js and call new PaystackPop().resumeTransaction({ accessCode, onSuccess, onCancel }). Pass ONE options object, because resumeTransaction takes a single argument and the older-looking resumeTransaction(accessCode, callbacks) silently falls back to a full-page redirect to Paystack. Stripe returns a checkoutUrl to send the buyer to. Bank transfer returns an account once the provider confirms it, so poll GET /v1/store/checkouts/:ref if it is null. Requires headless to be switched on for the workspace. Release the seats early with POST /v1/store/checkouts/:ref/cancel when the buyer walks away. Every rail returns the buyer to your returnUrl with ?checkout=<ref> appended, so they never see a FrontDesk page. Treat that redirect as a hint and confirm with GET /v1/store/checkouts/:ref. With a TEST key this creates a REAL order marked test (no money, no stock, no tickets) and charges against the provider sandbox — pay it with a provider test card. Where sandbox credentials are not wired, it validates and prices only: payment fields are null and orderRef is a synthetic test_ord_ value that resolves to nothing.

### GET /v1/store/checkouts/:ref
The state of a checkout, including the order ref once it is paid.
Auth: Authorization: Bearer fd_sk_… (secret, server only)
Scope: checkout:read (the umbrella scopes read/transact also satisfy it)
- ref (path, required): The checkout ref.
Returns: StoreCheckoutSessionView
NOTE: THIS is how you confirm a purchase. The return redirect is a browser navigation and can be lost, replayed or forged. Never fulfil on it alone. Safe to poll while a buyer is paying: when the checkout is still open we ask the payment provider directly before answering, so you get a real answer even if a webhook is late or never arrives. Polling every few seconds is fine and costs you nothing extra.

### POST /v1/store/customers/link
Attach your own signed-in user to this workspace's contacts, so their purchases and plans line up under one person.
Auth: Authorization: Bearer fd_sk_… (secret, server only)
Scope: customers:link (the umbrella scopes read/transact also satisfy it)
Body:
- email (required): The email YOUR auth system verified. Never a guessed or unverified address.
- externalRef (required): Your own user id (e.g. a Supabase Auth user id). The idempotency key: the same value always returns the same link.
- name: Display name. Fills an empty contact name, never overwrites a set one.
- phone: Optional phone for the contact.
Returns: StoreCustomerLinkView
NOTE: Only link identities your own auth verified (a confirmed email or OTP-verified phone) — this endpoint trusts your assertion because the key already proves you are the merchant's backend. Idempotent per externalRef: repeat calls return the SAME link and alreadyLinked=true, and the response shape is identical whether the contact existed before or not, so nothing here can be used to probe who is already a customer. Fires the customer.linked webhook exactly once, on the link. With a TEST key this validates fully and returns synthetic test_cus_/test_con_ refs that resolve to nothing, creating no contact.

### GET /v1/store/orders
Your own store orders, newest change last — built for keeping a local copy (a Supabase mirror, a dashboard) in sync.
Auth: Authorization: Bearer fd_sk_… (secret, server only)
Scope: orders:read (the umbrella scopes read/transact also satisfy it)
- updatedSince (query): ISO 8601. Only orders changed at or after this moment, ordered by updatedAt asc. Feed the largest updatedAt you received back as the next cursor; the >= comparison re-sends the boundary row, so upsert by ref.
- limit (query): Page size, 1 to 200. Defaults to 100.
Returns: StoreOrderRecord[]
NOTE: The key's env picks the set: a live key never sees test orders and a test key never sees live ones, and `test` is also on every row. In-progress savings plans (`saving`) never appear — they are not orders yet. A page shorter than `limit` means you are caught up. Deletions arrive as the order.deleted webhook (today that is sandbox retention removing 90-day-old test orders). This is a sync and back-office read: to confirm a single purchase, keep using GET /v1/store/checkouts/:ref.

### POST /v1/store/otp/send
Send a one-time password to your own customer over WhatsApp, from your own connected WhatsApp number.
Auth: Authorization: Bearer fd_sk_… (secret, server only)
Scope: otp:send (NOT implied by read or transact — the key must hold this scope by name, enabled per key in the portal)
Body:
- to (required): Your customer's number in full international format, e.g. +2348012345678.
- code: Your own code, digits only, up to 15 characters. Omit it and we mint a 6-digit one — which is also the ONLY way /v1/store/otp/verify can work, because a code you chose is one we never see in the clear.
- purpose: Your own label for what this code was for ("login", "payout"). Stored for your send log, never shown to the customer.
- expiresInMinutes: How long the code stays valid. Default 10, maximum 60.
- templateRef: Which authentication template to send. Omit it when the channel has one, which is what 'Set up OTP' creates.
- sender: Which number carries the code: 'own' (your connected WhatsApp number) or 'frontdesk' (ours). Omit it and your workspace's own setting decides, which is 'own' unless you changed it — so an integration written before this existed is unaffected. On 'frontdesk' the code arrives from FrontDesk rather than your business, because an authentication template's wording is fixed by WhatsApp and has no place for your name. Cannot be combined with templateRef: the template on our number is ours.
Returns: StoreOtpSendView
NOTE: This costs money on every send, whether or not your customer ever reads it: an authentication template is business-initiated, so the free 24-hour reply window does not apply. The response quotes what was charged. WhatsApp OTP in Nigeria is several times the price of SMS — the reasons to choose it are deliverability and one-tap copy, not cost, and an international destination costs roughly 11x the Nigerian rate. THE CODE IS NEVER RETURNED, even when we minted it: hold the challengeRef and call /v1/store/otp/verify. `to` comes back masked. Before this works the workspace needs a connected WhatsApp number and an approved authentication template (Set up OTP in the portal), and the destination's country on its allow-list, which starts as the workspace's own country only. Throttled per destination independently of this key's rate limit: 60 seconds between codes to one number, 5 an hour, 10 a day. Each KEY also has its own ceiling on total sends per rolling 24 hours (100 by default, settable per key in the portal), so one leaked credential cannot spend the workspace's whole daily WhatsApp allowance and take your other keys down with it. Nothing is charged when a guard refuses. WITH `sender: 'frontdesk'` none of the setup applies — no number to connect, no business verification, no template — but the code identifies FrontDesk rather than you, and the price is exactly the same. If we cannot send from our number it returns 503 OTP_SENDER_UNAVAILABLE and charges nothing; it never quietly falls back to yours, because a code from an unexpected number that you paid for is worse than a refusal you can read.

### POST /v1/store/otp/verify
Check a code your customer typed against a challenge we minted.
Auth: Authorization: Bearer fd_sk_… (secret, server only)
Scope: otp:verify (NOT implied by read or transact — the key must hold this scope by name, enabled per key in the portal)
Body:
- challengeRef (required): The challengeRef from /v1/store/otp/send.
- code (required): Exactly what your customer typed.
Returns: StoreOtpVerifyView
NOTE: 200 means verified. A failure is a RESULT rather than an API error, so it answers 422 with {verified:false, reason} instead of the usual error envelope — branch on `verified` either way. `reason` is invalid, expired or too_many_attempts. An unknown challengeRef, an expired challenge and a wrong code all answer identically on purpose, so this cannot be used to discover which refs exist. Five wrong guesses burns the challenge; so does one right one, because a code is good exactly once — send a new one rather than retrying. If you supplied your own `code` on send, this answers 409: we never saw it in the clear, and telling you `verified: true` for a check we cannot actually make would be worse than saying so.

### POST /v1/store/checkouts/:ref/cancel
Cancel an open checkout and release the seats it was holding.
Auth: Authorization: Bearer fd_sk_… (secret, server only)
Scope: checkout:cancel (the umbrella scopes read/transact also satisfy it)
- ref (path, required): The checkout ref.
Returns: StoreCheckoutSessionView
NOTE: Call this when your buyer abandons the payment step. A headless ticket checkout holds its tiers against capacity until expiresAt, so cancelling puts them back on sale straight away instead of leaving them out of stock for the rest of the window. Cancelling a checkout that is already paid returns 409, and a checkout that lapses on its own is released by us.

## Rendering a product page

GET /v1/store/products/:slug returns everything a full product page needs. Every block
below is OPTIONAL: render it only when its field is present, and a bare product should
show none of this chrome.

PRODUCT INFO (the `info` object): `highlights` is the checkmark list under the price.
Build a Details table from `specs` ({label, value}[]) plus brand, modelName, manufacturer,
countryOfOrigin and sku. `sustainabilityText` and `careInstructions` are their own
accordions; warranty is `warrantyText` (or "N months" from `warrantyMonths`).
`longDescription` is the prose block, and `descriptionBlocks` is an ordered rich list
(text and image blocks) rendered after it.

VARIATION GROUPS (the `options` array): present when the merchant sells the product along
several axes (Size x Colour). Render ONE picker per group, drawn per that group's own
`display`: `dropdown` -> a select, `text` -> chips, `color` -> swatches from the value's
`swatchHex`, `image` -> tiles from the value's `media[0]`. The buyer picks one value per
group; the chosen set resolves to the ONE variant whose `optionValueRefs` holds exactly
those value refs — that variant's ref is what you send to checkout, unchanged. A value
whose every remaining variant is sold out (or unpriced in the buyer's currency) should be
dimmed. A value's `media` swaps the gallery when it is selected. When `options` is ABSENT,
fall back to the flat variant picker below — that is the normal case.

VARIANT PICKER (no `options`): switch the UI on `variantDisplay`. `text` -> name chips. `dropdown` ->
a single select, for long or numerous names. `image` -> square
image swatches from each variant's media[0], and selecting one swaps the gallery to that
variant's media. `color` -> circular swatches from `swatchHex`, falling back to a text
chip for a variant whose swatchHex is null. A variant with soldOut:true stays visible and
selectable, just not addable.

PRICE: `priceMinor` is minor units. `compareAtMinor` drives the strikethrough and the
percent-off badge. `prices[]` carries the other accepted currencies: pick the buyer's,
and hide a variant with no price in it.

THE CALL TO ACTION, in this order:

1. Not sold out -> add to cart, quantity capped on the variant's `availableQty`
   (null = untracked, no cap; only reveal the number when it is low).
2. `preorderable: true` -> a pre-order CTA REPLACES the sold-out state. Cap quantity on
   `preorderRemaining` (availableQty is 0 by definition). Show `preorderEtaText` under the
   CTA only when present. NEVER hardcode shipping copy. When `preorderDepositType` is set,
   say "Pay N% now" (percent) or the fixed amount (minor units); the exact charge is
   struck on the order total server-side, so never compute it yourself.
3. `saveForItSaveable: true` -> offer the savings-plan path.
4. Otherwise sold out; when `restockAlertsEnabled` is true, offer a restock alert.

REVIEWS: render stars only when `reviews` is present AND `reviewsEnabled` is true.
No stars otherwise. Never fabricate a rating from nothing.

STALE CARTS: a cart lives in the buyer's storage, so recheck it on return with
GET /v1/store/availability?variantRefs=<csv>. A ref missing from the `variants` map is no
longer purchasable: drop the line. A ref listed in `preorderable` is still buyable at 0
stock: cap it on `preorderRemaining` instead of dropping it.

CARDS AND LISTS: PublicProductSummary carries `preorderable` and `saveForItSaveable` for
pill states (both REPLACE the grey sold-out pill: the item is still gettable),
`compareAtMinorFrom` + `showSaleBadge` for the sale badge, and `ratingAvg`/`ratingCount`
for the star line (absent under the cold-start floor: show no stars).

## Taking payment

You never handle card details, and you never price a cart yourself.

1. Your SERVER calls POST /v1/store/checkouts with an Idempotency-Key. Every variantRef
   must be a live one from GET /v1/store/products: an unknown or unpublished ref is
   refused with 400 VALIDATION_ERROR (the bad refs are in `error.details.invalid`), so a
   typo fails on your server instead of in front of your buyer.
2. Send the buyer to the `hostedUrl` you get back. They pay on the merchant's own
   FrontDesk-hosted page, so their branding does not change mid-payment.
3. We send them back to your `returnUrl` with ?checkout=<ref>&order=<ref>. Only a PAID
   checkout gets there: a buyer who backs out of a payment returns to the hosted page,
   a retry pays the same order, and reopening hostedUrl resumes it.
4. Confirm with GET /v1/store/checkouts/:ref, or wait for the checkout.completed webhook.

DO NOT fulfil on the redirect in step 3. It is a browser navigation: it can be lost,
replayed or forged. Step 4 is the only proof.

Prices shown by the read endpoints are for DISPLAY. The order is priced when the buyer
pays, so a price that moved in between is resolved there, not by you.

## Registering for a free event

A free RSVP needs no server at all. This is the one write a publishable key may make.

1. GET /v1/store/events/:slug. Render the tiers whose `kind` is `free`; each carries
   `formFields` (the questions to ask, keyed by `key`), `groupSize`, `minPerOrder`,
   `maxPerOrder`, `requiresAttendeeDetails` and `soldOut`. The event carries `minAge`
   and `dobMode`.
2. POST /v1/store/events/:slug/register straight from the browser with the publishable
   key: `tickets` (same shape as checkout: ticketTypeRef, quantity, positional
   `attendees` to name each seat), `contact` (name, and an email and/or phone),
   `responses` keyed by each field's `key`, and `dateOfBirth` when a tier is age-gated.
   A plus-one is quantity 2 with the guest named in the second attendees entry.
3. Show the `reference` and `status` you get back and tell the guest to check their
   email: FrontDesk sends the confirmation, the .ics invite and the ticket PDF itself.

FREE tiers only. A paid tier answers 402 TIER_REQUIRES_PAYMENT: open a checkout for it
from your server instead. Every rule the hosted page applies runs here too (sales
window, capacity, min/max per order, required questions, age gate).

Duplicates are quiet. An email that already holds a seat on the event gets the SAME 201
as a first registration (their existing reference and status), the confirmation is
re-sent at most every 10 minutes, and no second seat is issued. So a retry is always
safe when an email is given, and no Idempotency-Key is needed. There is no endpoint to
read registrations back: subscribe to the attendee.registered webhook, and the organiser
sees every guest in their portal.

## Sandbox (test mode)

An `fd_sk_test_…` key opens a TEST checkout. The hosted page shows a test banner over the
REAL payment rails wired to the provider sandbox: pay with a provider test card (Paystack
offers a Success option; card 4084 0840 8408 4081 also works) and the whole loop runs —
open, hosted page, charge, return, confirm, webhook — without a kobo moving.

A paid test checkout creates a REAL order marked test everywhere: fetch it, list it, get
checkout.completed and order webhooks for it. What it never does: move money, credit a
wallet, post to a ledger, hold stock or seats, issue tickets, or send buyer receipts. It
never appears in the merchant's live views or sales figures.

Rails without a sandbox (bank transfer via PVB, Flutterwave) are not offered in test mode.
Mode comes from the key that opened the session and cannot be set by the caller. Test
orders are retained for 90 days, then hard-deleted.

A free event registration from a test key runs every check and answers test:true with a
test_ reference. It writes no guest, sends no email and fires no webhook.

## Buyers signing in

Buyers can have a FrontDesk account and see their own history in your app.
Send `X-FD-Store-Key: fd_pk_…` alongside the buyer calls so we know which merchant you
are: the session we mint is then scoped to that merchant, and only ever shows purchases
made with them.

- POST /v1/customer/auth/start  { email } -> tells you which factor to ask for
- POST /v1/customer/auth/verify { email, code } -> returns a session token
- GET  /v1/customer/purchases   (Bearer <session token>) -> their history with you

PIN entry, two-factor setup and anything that moves money stay on FrontDesk-hosted
pages. We hand you identity; we keep credentials and money.

A purchase marked `actionable: false` was matched to the buyer by email rather than
bought while signed in. Show it, but do not offer refunds or cancellation on it.

## Webhooks

Signed: `X-FD-Signature: sha256=HMAC(secret, X-FD-Timestamp + "." + rawBody)`.
Compare in constant time, and reject a timestamp far from now.
Payloads carry refs only, on purpose. Re-fetch through the API for detail.
Retries back off for 24 hours; return 2xx quickly and do the work asynchronously.

- checkout.completed: A hosted checkout was paid. (checkoutRef, orderRef)
- checkout.expired: A checkout link lapsed unpaid. (checkoutRef)
- order.updated: An order's fulfilment status changed. (orderRef, status, fulfillmentStatus)
- form.submitted: A form submission was recorded. (submissionRef, formSlug, formRef)
- attendee.registered: A guest registered for a free event: through your own page, the hosted storefront, or the public RSVP link. Never fires for a test key. (attendeeRef, eventRef, eventSlug, ticketTypeRef, status, attendeeCount, groupRef, source)
- customer.linked: A buyer account was linked to one of your contacts. (customerRef, contactRef)
- product.deleted: A product was deleted from the store. Remove it from any local copy. (productRef, slug)
- order.deleted: An order was removed. Today: sandbox retention hard-deleting test orders after 90 days. (orderRef, test, reason)

## MCP

There is an MCP server at POST /v1/store/mcp. Authenticate with the same key you would
use for HTTP: a publishable key gets the read tools and free event registration, a secret
key also gets the checkout tools. The workspace comes from the key, so tool arguments
cannot select a different one.

Methods: initialize, tools/list, tools/call. Tool names are stable, e.g.
store_get_storefront, store_get_products_slug, store_post_events_slug_register,
store_post_checkouts.

## Supabase backend

If your stack is Supabase you do not have to build the server side yourself. The merchant
connects their own Supabase project from Developers → Supabase and FrontDesk installs it:
Edge Functions holding a dedicated scoped secret key (server-side only, your frontend never
sees a key at all), a signed webhook receiver, and a `frontdesk` schema with realtime
checkout rows behind default-deny RLS. Your frontend calls those functions instead of this
API directly.

Since v2 the schema also mirrors the catalogue (`frontdesk.products`) and the merchant's own
orders (`frontdesk.orders`, with a `test` flag): webhooks keep them fresh, a scheduled
`frontdesk-sync` function pulls the delta reads (`updatedSince`) for truth, and
product.deleted / order.deleted events remove rows. Query and join them locally; FrontDesk
wins every conflict. Nothing money-shaped is ever mirrored.

One Supabase project per workspace: installing a second workspace into the same project
overwrites the first one's secrets. Disconnecting revokes the key and our access; the
tables, functions and data in the project stay exactly as they are.

The credentials rule holds inside your own code too: the browser uses `fd_pk_…` from an
allowed origin; anything server-side (Node, Deno, an Edge Function) uses `fd_sk_…`. A
publishable key called from a server carries no browser origin and is refused.

## Rate limits

Reads 600/min per key, writes 60/min, free event registrations 300/min, buyer auth 20/min.
A per-IP ceiling sits alongside them. On 429, honour Retry-After. These are the defaults,
not a wall: if your integration
genuinely needs more, ask us and we raise your workspace specifically.

## Caching

Catalogue reads (storefront, products, events, collections, forms, tables,
catalogs, files, notes, delivery-zones) may be served from a 60-second cache, so an edit
can take up to a minute to appear through the API; X-FD-Cache says hit or miss.
Availability, slots, checkouts and orders are NEVER cached — what they say is live.
Responses are private to your keys: cache them on your side per key, never in a shared
cache keyed by URL.