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: 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 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 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