Skip to content

Hosted litecheckout

litecheckout is a litecommerce-hosted, tenant-branded customer surface: checkout and payment, order status, and the signed-in account center (profile, addresses, order history, returns). A tenant gets all of it at {tenant}.litecheckout.io with no integration work — it's the batteries-included alternative to building a BYO checkout.

Under the hood it drives the exact same public APIs a BYO storefront would: the checkout-session contract for payment and the customer-account API for the account center. The difference is who renders the UI — litecommerce, instead of you.

Origins

litecheckout resolves the tenant from the subdomain, and the environment from where it runs (ADR-004):

  • Production — {tenant}.litecheckout.io
  • Preview / staging — {tenant}.preview.litecheckout.io

The tenant slug is the leftmost label, so acme.litecheckout.io serves the acme tenant. Every page resolves its tenant per-request from the host — there is no per-tenant deploy.

What it serves

Live today:

  • Checkout — /session/<token>: the tenant-branded payment surface over a checkout session.
  • Order status — /order/<token>/status: read-only post-purchase status (the o-token page).
  • Account — /account: signed-in home for profile, addresses, orders, and returns. Returns are started from a signed-in order (see Customer accounts).

Reserved seams (the route exists but renders a placeholder until its API contract lands — they do not work yet):

  • Payment retry — /payment/<token>: a tokenized re-pay surface, waiting on the payment-recovery token family. Today, payment happens on the /session/<token> checkout link.
  • Tokenized return — /order/<token>/return: a from-email return entry, waiting on the order-token return contract. Today, returns go through the signed-in account.

Checkout and account both require what their underlying APIs require — a checkout session token for the payment flow, a customer session for the account pages — and the token-addressed pages (/order/..., /payment/...) are reached from emailed links carrying opaque, hash-at-rest tokens.

Adopting it from a storefront

A storefront doesn't have to choose all-or-nothing. Each customer surface — checkout, order status, order history, returns, account, saved payment methods — can be handed to hosted litecheckout independently or kept first-party, via per-area env flags on the storefront (NEXT_PUBLIC_HOSTED_*). Everything defaults to first-party: with no flags set, the storefront behaves exactly as before, and flipping an area becomes a config change rather than a refactor.

When an area is hosted, the storefront redirects that surface to the matching {tenant}.litecheckout.io route instead of rendering it itself. Enabling any area also requires setting NEXT_PUBLIC_LITECHECKOUT_BASE_URL on the storefront (the hosted origin the redirects target) — with a flag on but the base URL unset, the redirect builder throws rather than guess. A typical rollout enables checkout + order status first, then order history + returns, then the full account center.

"Independently" has limits — some areas depend on another being hosted too, and the storefront seam's coherence check warns when a combination is incoherent:

  • Order status is produced hosted-side by hosted checkout — enable HOSTED_CHECKOUT alongside HOSTED_ORDER_STATUS, or status falls back to the first-party confirmation.
  • Returns start from order detail, so HOSTED_RETURNS pairs with HOSTED_ORDER_HISTORY (otherwise a first-party order detail just deep-links out to the hosted return flow).
  • Account, order history, and saved payment methods assume an authenticated customer, so they pair with HOSTED_CUSTOMER_AUTH — without it they fall back to email-match order lookup, and saved payment methods require it outright.

The suggested rollout above (checkout + order status, then history + returns, then account) follows these dependencies rather than flipping flags at random.

This per-area seam means a tenant can launch on hosted checkout immediately and migrate to a BYO surface later (or vice-versa) without re-platforming.

Hosted vs BYO — when to use which

  • Hosted litecheckout — fastest path to a working, tenant-branded checkout and account experience; litecommerce owns the UI, upgrades, and security posture (httpOnly session cookies, same-origin guards, tokenized links).
  • BYO — full control of the customer UI, at the cost of building and maintaining it against the checkout-session and customer-account APIs.

Both run on the same server-authoritative commerce core: litecommerce computes totals, owns Stripe objects, and confirms orders from the webhook regardless of which surface rendered the page.

Related