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: M3 foundation (0.1.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 four companion references 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 plus its references/.

The four 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/storefront-checklist.md — implementation checklist.
  • references/validation-checklist.md — review checklist for generated code.

Pasting only SKILL.md will leave out the references it relies on.

What it helps you build

Today the skill builds against the shipped public surface (/api/v1/public/*):

  • 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.
  • 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.
  • 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.

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. POST /api/v1/public/checkout/sessions/:token/payment-session — token-only; do not send x-organization-slug
  5. Render Stripe Payment Element from the returned 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. Hosted litecheckout pages, platform-link redirects, booking checkout modes, and subscription checkout modes remain separate capabilities; build them only when the matrix and OpenAPI mark them shipped.

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