---
name: litecommerce-storefront
description: Build or review a tenant-owned cartonium storefront against the shipped public and customer APIs, including catalog/content, cart and server-authoritative checkout, optional passwordless customer accounts, safe sign-in return continuity, orders/returns, engagement, saved payment methods, and customer quote/invoice/contract actions. Use when implementing, extending, or validating custom storefront journeys without leaking secrets or treating planned capabilities as live.
---

# cartonium Storefront Skill

Every storefront call must carry its current origin. Browsers supply `Origin`;
SSR/BFF transports derive `x-storefront-origin` from the current incoming
request. Domains alone selects Production or Sandbox data, including token-only
checkout requests. No separate mode/URL environment setting and no Live retry
are allowed. Missing, unknown or conflicting context fails closed; preserve the
route's tenant and credential requirements.

Version: customer-surface refresh (`0.2.0`).

Use this skill when building a tenant-owned storefront on cartonium. The
storefront can be Next.js, Astro, Remix, plain React, or another web stack, but
cartonium remains the backend of record for catalog, content, inventory,
checkout sessions, payments, orders, returns, shipping rates, customer
accounts, and shared-commerce documents.

This is a tenant-facing implementation skill, not an internal cartonium repo
agent. Prefer small, production-shaped storefront code over demo-only scaffolds.

## Start Here

1. Ask the merchant for the non-secret integration brief from **Settings → API
   & webhooks → Connection details** (`/settings#connection-details`), where
   that handoff is available. It is rolling out through staging; do not assume
   every Admin deployment has it. The brief supplies the current environment,
   tenant slug, API base URL and resolved hosted account URL. Otherwise obtain
   those public values from the operator; never request a merchant session or
   guess hosted URLs from a deployment hostname. Confirm the API deployment and
   registered storefront address: Domains selects the commerce data; calling
   Preview does not select Sandbox. Follow the setup
   and schema-identity checks in `references/api-patterns.md` before building.
   Sandbox is in progress; use it for staging validation only with operator
   confirmation. It delivers no transactional email, including OTP, newsletter
   confirmation and emailed action links; email-dependent acceptance stays unverified.
2. Send `x-organization-slug: <tenant-slug>` on tenant-resolving public
   requests. Server calls forward their actual incoming storefront origin as
   `x-storefront-origin`; browsers supply `Origin`. No separate mode setting is
   required, and missing context must not fall back to Live.
   Checkout handoff omits the tenant header, but can still need a customer
   credential; follow the conditional identity rule in `references/api-patterns.md`.
3. Build against `/api/v1/public/*` first, then use the documented
   `/api/v1/customer/*` surface for customer sessions, account data, and scoped
   actions. Do not use merchant, platform, or internal APIs for storefront work.
4. Read `references/capabilities.md` before claiming a capability is live. That
   file is generated from cartonium's feature-status source of truth.
5. Use the OpenAPI reference for endpoint details. Do not copy request or
   response schemas into generated code unless the user explicitly asks.

## Non-Negotiables

- Never put server secrets in browser code or public environment variables:
  `SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_SECRET_KEY`, `SUPABASE_JWT_SECRET`,
  `POSTGRES_*`, tenant secret keys, Stripe secrets, or private API tokens.
- Browser code may use only browser-safe public values. Prefer server-side API
  calls for framework code, especially when composing cart/order flows.
- Treat cartonium errors as a standard envelope and dispatch checkout
  recovery by HTTP status, `code`, and `details` together. Every error body
  carries a `code`, including `5xx`. Named `503` refusals keep their own
  `details.retry` or support instructions; only the documented generic
  `503 / INTERNAL_ERROR` readiness response permits bounded rollout retry.
  A `502` is not uniquely a card-only refusal: bind-time tax failures and
  payment-handoff failures have different recovery. Never automatically retry
  `PAYMENT_HANDOFF_POLICY_INVARIANT_VIOLATION` or an unrecognized failure. Follow
  the error-recovery table in `references/api-patterns.md`.
- `409 COMPOSITION_REVISION_STALE`, and any conflict whose `code` or
  `details.reason` you do not recognize, is fail-closed: surface a blocked
  recovery state and never retry-loop, reconfirm, restart checkout, or
  recharge. `CHECKOUT_PREPARED_PAYMENT_CONFLICT` is **not** blanket-blocked —
  it carries a per-reason recovery contract, parts of which are deliberately
  retryable. Follow the reason table in `references/api-patterns.md`; blocking
  it wholesale strands a recoverable checkout.
- Handle empty catalogs, empty collections, missing images, unavailable
  variants, and temporarily absent optional features gracefully.
- Storefronts are CUSTOM by default. Do not assume every tenant has a
  cartonium-hosted subdomain.
- Keep guest checkout available when customer accounts are enabled. Restrict
  checkout `returnTo` to an explicit route/parameter allowlist (same-origin is
  not enough) and preserve the cart/draft before starting sign-in; follow
  `references/tenant-storefront-contract.md`.

## Recommended Build Flow

1. Tenant shell: resolve canonical origin with public site config; build
   navigation, catalog listing, search/filter controls, and empty states.
2. Product detail: render `item.shortDescription` as compact blurb copy and
   `item.description` as the primary PDP body; then add variant selection, media
   gallery, availability check, bundle/discount preview callouts, and
   add-to-cart action. Use metafields for structured extras or explicit
   variant-specific overrides, not as the default product description source.
   When a tenant explicitly needs variant-specific body copy, use the
   conventional override key `metafields.description` on the selected variant
   and fall back to `item.description`.
3. Collections and pages: merchandising collections, CMS pages, and navigation
   derived from public content.
4. Cart: local cart state is editable; line-item and preview calls are still
   estimates until the server-side checkout session is repriced and bound.
   Render the standard cart summary — subtotal, itemized discounts/coupon
   names, shipping, tax disclosure, and an estimated-vs-bound total — the same
   way across drawer, full cart, and checkout handoff, per
   `references/cart-summary-contract.md`.
5. Account-aware continuity (optional): preserve guest checkout, show
   “Already have an account? Sign in” at contact/address entry, validate the
   explicit checkout return allowlist, restore the draft after auth, and prefill
   only blank fields from the matching customer profile/address selection. See
   `references/tenant-storefront-contract.md`.
6. BYO checkout: create/reprice/bind a checkout session with
   `x-organization-slug`, then branch on the bind response's
   `requiresFreeConfirmation`: true uses tenant-scoped free confirmation for
   zero or positive totals below the provider's per-currency minimum; false
   requests the tenant-header-free payment handoff without that header.
   Initialize Stripe.js with the returned `publishableKey` and optional
   `stripeAccountId`, then render Stripe Payment Element with `clientSecret`.
   Never create Stripe PaymentIntents directly. Card is the only eligible method
   at one-time checkout — do not offer ACH or other asynchronous methods. After
   **every** successful bind, discard the held Payment Element and client secret
   unconditionally, then use that new response's flag for the same completion
   decision. Never compare the total to a client-side provider minimum or infer
   whether the bind was an exact replay. Poll status on the session read at
   3-second intervals for at
   most 20 reads, and stop on the documented conditions. See "Discard And
   Reacquire", "Bounded Polling For Checkout Status", and
   "`COMPOSITION_REVISION_STALE`" in `references/api-patterns.md`.
7. Legacy order placement: `POST /api/v1/public/orders` remains a deprecated
   line-item-only compatibility producer. New checkout builds use sessions;
   retain existing callers under the documented compatibility window.
8. Post-purchase: confirmation/status pages use public order reads. The
   order-confirmation email also carries a read-only `o`-token status link.
   A storefront can render its own page against
   `GET /api/v1/public/orders/token/:token`; pass the token through verbatim.
   The route does not require a customer session, but it still requires
   `x-organization-slug`. New order/return links use `orderReference` plus the
   applicable checkout or customer credential; UUID/email routes remain
   deprecated compatibility paths, with no announced sunset date.
9. Customer accounts (optional tier): passwordless sign-in
   (`request-link`/`request-otp`/`verify` under `/api/v1/public/customer/auth`)
   plus the authenticated `/api/v1/customer/account/*` surface — profile,
   addresses, order history, returns. See "Customer Accounts And Sign-In" in
   `references/api-patterns.md`; keep the session token server-side, and never
   branch UI on the always-neutral challenge responses.
10. Customer engagement and documents: implement newsletter capture and its
    platform-owned confirmation/unsubscribe landing contract,
    back-in-stock signup, reviews, saved-payment-method management, and
    customer quote/invoice/contract actions only from the deliberately
    supported map in `references/api-patterns.md`.
11. Hosted cartonium checkout — **matrix-gated**: the hand-off path (a tenant hands
   checkout/status/account surfaces to the cartonium-hosted app instead of
   building them) applies only when `references/capabilities.md` marks the
   hosted surface shipped and the tenant brief selects it. Use
   `https://docs.litecommerce.io/guides/hosted-litecheckout` for the route map;
   do not invent hosted URLs. Never expose database ids in customer URLs.

## Storefront Origin Posture

Build for CUSTOM tenant storefronts by default. Read the public site-config
contract for an environment-aware canonical origin and keep an explicit
same-origin fallback. Hosted subdomains and platform-sent redirects can coexist,
but do not infer one from the tenant slug or invent checkout/status URLs.

## Versioning

This skill is refreshed when shipped public contracts or truthful capability
status changes. The generated capability matrix and current OpenAPI map control
what an agent may build against; a registered epic or roadmap entry is not
itself an integration contract. E17 tenant webhooks and event delivery are not
currently scheduled, so do not invent an event catalog, subscription endpoint,
payload, or signing scheme. Shared-commerce customer
quote/invoice/contract actions are already shipped in the current OpenAPI map.
Do not patch a tenant storefront against an imagined future endpoint; update
the skill or point to the current OpenAPI/docs contract first.

## References

- [references/capabilities.md](references/capabilities.md) - generated live/in-progress/planned matrix.
- [references/api-patterns.md](references/api-patterns.md) - endpoint map, environment setup, newsletter destinations, and wire-level API gotchas.
- [references/cart-summary-contract.md](references/cart-summary-contract.md) - the standard cart summary rows +
  estimate-vs-binding disclosure.
- [references/tenant-storefront-contract.md](references/tenant-storefront-contract.md) - guest/account navigation, safe
  sign-in return, prefill, checkout, and post-purchase continuity.
- [references/storefront-checklist.md](references/storefront-checklist.md) - implementation checklist.
- [references/validation-checklist.md](references/validation-checklist.md) - review checklist for generated code.
- [examples/nextjs-product-grid.md](examples/nextjs-product-grid.md) - server-rendered catalog forward-test.
- [examples/product-detail-page.md](examples/product-detail-page.md) - PDP copy/variant/availability forward-test.
- [examples/litecheckout-handoff.md](examples/litecheckout-handoff.md) - BYO checkout-session/payment forward-test.
- [examples/tenant-account-checkout-journey.md](examples/tenant-account-checkout-journey.md) - guest-to-returning-customer
  continuity forward-test.
- [examples/storefront-brief-template.md](examples/storefront-brief-template.md) - tenant input/acceptance template.
- API reference: `https://docs.litecommerce.io/api-reference`
- Guides: `https://docs.litecommerce.io/guides/byo-checkout`,
  `https://docs.litecommerce.io/guides/customer-accounts`,
  `https://docs.litecommerce.io/guides/order-status`,
  `https://docs.litecommerce.io/guides/hosted-litecheckout`
