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.

Return and action destinations

Hosted litecheckout receives its customer-facing URLs from the API checkout summary. The API resolves explicit checkout settings first, then safe defaults, so storefronts do not have to infer destinations from deployment hosts or organization profile fields.

Surface	Setting	Default when blank
Back to store / order status return	`returnToStoreUrl`	The tenant storefront origin, then a neutral litecommerce page when configured, then `null`
Completed checkout redirect	`postCheckoutRedirectUrl`	`returnToStoreUrl`, then the tenant storefront origin, then a neutral litecommerce page when configured, then `null`
Expired checkout retry	`checkoutRetryUrl`	`returnToStoreUrl`, then the tenant storefront origin, then a neutral litecommerce page when configured, then `null`
Canceled checkout	`checkoutCancelUrl`	`checkoutRetryUrl`, then `returnToStoreUrl`, then the tenant storefront origin, then a neutral litecommerce page when configured, then `null`
Account and sign-in links	`customerActionBaseUrl`	The tenant's hosted litecheckout account origin

Explicit redirect destinations are only used when they point at a trusted origin: the tenant's verified custom domain for the current environment, the tenant's own hosted litecheckout origin, or an operator-approved shared origin. Untrusted or invalid values are ignored rather than sent to shoppers.

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.