Skip to content

Agent storefront skill

The cartonium Storefront Skill is a skill package you hand your coding agent — Claude, Codex, Cursor, or similar — so it builds a tenant-owned storefront correctly against the cartonium public API. It teaches the route conventions, tenant context, capability boundaries, and secret-handling rules up front, so the generated storefront talks to the same API that powers our reference storefronts instead of guessing.

It's a tenant-facing implementation skill, not an internal cartonium repo agent. Current version: customer-surface refresh (0.2.0) — updated when public contracts or truthful capability status changes.

Who it's for

Tenant teams building a custom storefront on cartonium — Next.js, Astro, Remix, plain React, or any other web stack. cartonium stays the backend of record for catalog, content, inventory, checkout sessions, payments, orders, returns, and shipping rates; your storefront owns brand, layout, and customer experience.

What you'll need

Give your agent these and it can start:

  • API deployment and base URL — Production is https://api.litecommerce.io/api/v1; Preview is https://api.preview.litecommerce.io/api/v1. Compare runtime/reference schema identity before integration using Environments & schema identity.
  • Registered storefront address — configure Production and Sandbox (Preview/Staging) in Settings → Domains. Browsers supply Origin; server calls forward the actual incoming storefront origin as x-storefront-origin. Domains selects the corresponding data, with no extra mode setting or Live fallback. Calling the Preview API alone does not select Sandbox or guarantee test payments. Missing, unknown or conflicting origin context is rejected. Sandbox is the in-progress storefront-sandbox capability; use it for staging validation only when the operator confirms the tenant's setup. It delivers no transactional email, including sign-in OTP, newsletter confirmation or emailed order/action links, so it cannot prove email-dependent acceptance.
  • Your tenant (organization) slug — sent as the x-organization-slug header on tenant-resolving public requests. Tenant-header-free checkout handoff routes document their own exception. See Tenants & context.
  • Your storefront requirements — the pages and flows you want.
  • A framework preference (optional) — Next.js, Astro, Remix, etc.

Install it

The skill lives on this docs site as plain Markdown. SKILL.md is the entry file, and it pulls in six companion references plus five forward-test/example artifacts from the same folder — so your agent needs the whole set, not SKILL.md on its own. Two ways to give it to your agent:

  • Point a web-capable agent at SKILL.md — it resolves the references from the same folder as it reads:

    https://docs.litecommerce.io/skills/litecommerce-storefront/SKILL.md
    
  • Save the whole folder into your agent's skill/rules config — SKILL.md, references/, and examples/.

The six references are:

  • references/capabilities.md — the live / in-progress / planned matrix, generated from cartonium's feature-status source of truth.
  • references/api-patterns.md — endpoint map and wire-level gotchas.
  • references/cart-summary-contract.md — shared cart/checkout summary and estimate-to-bound disclosure.
  • references/tenant-storefront-contract.md — guest/account navigation, safe sign-in return, draft/prefill, checkout, and post-purchase continuity.
  • references/storefront-checklist.md — implementation checklist.
  • references/validation-checklist.md — review checklist for generated code.

The five example artifacts are: examples/nextjs-product-grid.md, examples/product-detail-page.md, examples/litecheckout-handoff.md, examples/tenant-account-checkout-journey.md, and examples/storefront-brief-template.md.

Pasting only SKILL.md will leave out the references and forward-test artifacts it relies on.

Download or refresh the complete package

This shell command needs curl. It downloads all 12 files into a new folder and prints its path only after every download succeeds. It does not install a skill or overwrite an existing copy. Use the completed folder in your agent's skill/rules configuration; retain its references/ and examples/ layout.

(
  set -eu
  skill_base="https://docs.litecommerce.io/skills/litecommerce-storefront"
  skill_directory="$(mktemp -d "${TMPDIR:-/tmp}/litecommerce-storefront.XXXXXX")"
  for skill_file in \
    SKILL.md \
    references/capabilities.md \
    references/api-patterns.md \
    references/cart-summary-contract.md \
    references/tenant-storefront-contract.md \
    references/storefront-checklist.md \
    references/validation-checklist.md \
    examples/nextjs-product-grid.md \
    examples/product-detail-page.md \
    examples/litecheckout-handoff.md \
    examples/tenant-account-checkout-journey.md \
    examples/storefront-brief-template.md
  do
    mkdir -p "$skill_directory/$(dirname "$skill_file")"
    curl --fail --silent --show-error --location \
      "$skill_base/$skill_file" --output "$skill_directory/$skill_file"
  done
  printf 'Complete Skill folder: %s\n' "$skill_directory"
)

If a download fails, do not use the partial folder. For an update, run the same command to obtain another complete copy, review changes and any local customizations, then switch your agent to that folder. Keep your old copy and custom files until you have reconciled them. Refresh the whole package together; updating SKILL.md alone leaves stale companion contracts.

What it helps you build

Today the skill builds against the shipped tenant public and customer surfaces (/api/v1/public/* plus the documented /api/v1/customer/* routes):

  • Catalog — listing pages, product cards, search/filter controls, and empty states wired to public catalog reads.
  • Product detail — variant selection, media gallery, availability checks, and bundle/discount preview callouts.
  • Collections & CMS pages — merchandising collections and content-driven navigation.
  • Tenant shell & engagement — canonical site config, newsletter signup, back-in-stock capture, product reviews, and protected abandoned-cart capture.
  • Inventory & availability — on-hand / available display per variant.
  • Cart and BYO checkout — cart displays stay editable, then checkout sessions create/reprice/bind the server-authoritative total and issue the cartonium Stripe Payment Element handoff, or complete a no-charge checkout when the bound summary's requiresFreeConfirmation is true.
  • Legacy compatibility — line-item-only public order creation and UUID/email order/return routes remain deprecated, with no announced sunset date. New builds use checkout sessions and reference-based order/return flows with the applicable credential.
  • Post-purchase — confirmation and status pages from public order reads; new return flows use customer ownership/session or issued action authority; guest order recovery remains available without prior account registration.
  • Optional customer continuity — guest checkout stays available; returning customers can sign in contextually, return only to a validated tenant-local checkout target from an explicit route/parameter allowlist, restore their cart/draft, and prefill only blank profile/address fields before reviewing and binding.
  • Account and document actions — saved payment-method management, customer order/return history, and customer-visible quote, invoice, and contract reads/actions.

It checks capabilities.md before claiming any capability is live. Hosted cartonium checkout and customer accounts are shipped optional surfaces; a tenant-owned storefront can use them without building its own checkout or account UI. Bookings and other in-progress or planned capabilities retain their own availability and activation boundaries. A published route alone does not establish that a feature is live.

Safety rules it enforces

The skill bakes in cartonium's non-negotiables, so generated code stays safe:

  • Public routes first. It uses /api/v1/public/* for storefront work and won't reach for merchant, platform, or internal APIs unless you explicitly ask for an authenticated admin surface.
  • No server secrets in the browser — never a Supabase service-role key, Stripe secret, Postgres credential, or private token in client code or public env vars. See Auth & roles.
  • Graceful states — it treats the error envelope as a standard shape and handles empty catalogs, missing images, and unavailable variants instead of crashing.
  • Custom by default — it assumes a tenant-owned storefront and won't invent a cartonium-hosted subdomain or redirect URL.

Checkout and customer accounts

The BYO checkout API contract is live. The skill should wire custom checkout UI to the public checkout-session sequence:

  1. POST /api/v1/public/checkout/sessions
  2. POST /api/v1/public/checkout/sessions/:token/reprice
  3. POST /api/v1/public/checkout/sessions/:token/bind
  4. Branch on requiresFreeConfirmation from the bind response: when true, call POST /api/v1/public/checkout/sessions/:token/confirm-free with tenant context. This covers a zero total and a positive total below the provider's per-currency minimum. When false, call POST /api/v1/public/checkout/sessions/:token/payment-session — the route is tenant-header-free; do not send x-organization-slug. Never duplicate the provider minimum with a client-side amount comparison.
  5. For paid checkout, initialize Stripe.js from the returned publishableKey and optional stripeAccountId, render Stripe Payment Element from clientSecret, then trust cartonium webhook/order state for the durable result.

The storefront must not create Stripe PaymentIntents directly. It renders the Payment Element using the cartonium-created handoff.

For ordinary one-time cart checkout, payment handoff omits the tenant header but can still require customer authority. Bind, payment-session, and confirm-free recheck the checkout email: a currently verified customer requires a live matching CustomerSession, forwarded as bearer authority by the BYO backend. Preserve the guest path for an unverified email and follow the documented identity-conflict recovery without creating a second checkout. A cookie on another storefront/hosted origin does not reach the API.

Customer account APIs are published for profile, addresses, orders, returns, and saved payment methods. Tenant-owned checkout must keep guest checkout and offer “Already have an account? Sign in” contextually at contact/address entry; it preserves the draft across auth, accepts only a safe local return, and never overwrites non-blank guest fields during profile/address prefill. For checkout, the return allowlist is exact /checkout, optionally with one known BYO mode marker; unrelated same-origin paths, extra params, and fragments are rejected.

For optional hosted adoption, follow the hosted handoff guide: use the resolved tenant/environment destinations and the correct checkout or customer credential. Reference-storefront flags are not a portable integration contract, and a BYO session cookie is not shared with the hosted origin. Booking and subscription checkout modes retain their separate capability gates; the shipped hosted surface does not activate those modes or dormant checkout extensions. Use OpenAPI for the wire contract and the capability matrix for availability.

Newsletter signup is supported and remains neutral, double opt-in capture. The skill's Newsletter Action Destinations contract covers the platform-owned emailed links, the three tenant settings, trusted fallback order, and token-safe landings. Confirmation shows the verified platform acknowledgement first; unsubscribe and stale-link landings retain separate behavior. A query success flag or navigation is not proof. See Newsletter & subscribers for the destination table; do not invent action URLs or forward tokens into landing URLs or analytics.

Keep it current

The skill is updated when shipped public contracts or truthful capability status changes. capabilities.md is generated from the feature-status source of truth, so it's the authority on what's shipped, in-progress, or planned. A roadmap epic is not itself an integration contract. Don't patch a storefront against an imagined future endpoint — update the skill, or check the current API reference and docs contract first.