Skip to content

Agent storefront skill

The litecommerce 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 litecommerce 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 litecommerce repo agent. Current version: E3 customer-surface refresh (0.2.0) — refreshed each milestone as new public contracts ship.

Who it's for

Tenant teams building a custom storefront on litecommerce — Next.js, Astro, Remix, plain React, or any other web stack. litecommerce 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 base URL — production is https://api.litecommerce.io/api/v1.
  • Your tenant (organization) slug — sent as the x-organization-slug header on tenant-resolving public requests. Token-only 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 the entry URL — 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 litecommerce'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.

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 litecommerce Stripe Payment Element handoff, or confirm a server-bound zero-total checkout without Stripe.
  • Legacy order placement — POST /api/v1/public/orders is still available for line-item-only order creation, but new checkout builds should prefer checkout sessions.
  • Post-purchase — confirmation and status pages from public order reads; returns can use the email-match customer-lite flow or the customer account APIs when the storefront implements customer session auth.
  • 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, so it won't build against in-progress or planned features (e.g. bookings, subscriptions, or hosted litecheckout pages) as if they were shipped.

Safety rules it enforces

The skill bakes in litecommerce'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 litecommerce-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 from the server-bound total: call POST /api/v1/public/checkout/sessions/:token/confirm-free with tenant context when it is zero, or call POST /api/v1/public/checkout/sessions/:token/payment-session when it is positive — the payment-session route is token-only; do not send x-organization-slug
  5. For paid checkout, initialize Stripe.js from the returned publishableKey and optional stripeAccountId, render Stripe Payment Element from clientSecret, then trust litecommerce webhook/order state for the durable result.

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

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. Hosted litecheckout behavior remains a separate runtime surface; booking and subscription checkout modes remain capability-gated. Build any of them only when the matrix and OpenAPI mark them shipped.

Newsletter signup is supported. Detailed confirm/unsubscribe landing settings and redirect safeguards remain a separate docs follow-up in #992; the skill does not invent hardcoded success routes while that contract is pending.

Keep it current

The skill is refreshed by milestone. capabilities.md is generated from the feature-status source of truth, so it's the authority on what's shipped, in-progress, or planned. Don't patch a storefront against an imagined future endpoint — update the skill, or check the current API reference and docs contract first.

Related