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 ishttps://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 asx-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-progressstorefront-sandboxcapability; 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-slugheader 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/, andexamples/.
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
requiresFreeConfirmationis 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:
POST /api/v1/public/checkout/sessionsPOST /api/v1/public/checkout/sessions/:token/repricePOST /api/v1/public/checkout/sessions/:token/bind- Branch on
requiresFreeConfirmationfrom the bind response: when true, callPOST /api/v1/public/checkout/sessions/:token/confirm-freewith tenant context. This covers a zero total and a positive total below the provider's per-currency minimum. When false, callPOST /api/v1/public/checkout/sessions/:token/payment-session— the route is tenant-header-free; do not sendx-organization-slug. Never duplicate the provider minimum with a client-side amount comparison. - For paid checkout, initialize Stripe.js from the returned
publishableKeyand optionalstripeAccountId, render Stripe Payment Element fromclientSecret, 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.
Related
- Storefront integration — the public/merchant boundary and tenant-scoping rules the skill follows.
- API reference — every endpoint, from the OpenAPI spec.
- Quickstart — make your first public read by hand.