Skip to content

Order status links

After a confirmed order, litecommerce emails the customer a link to a read-only order-status page. The link carries an opaque o-family token (ADR-007: hashed at rest, tenant-scoped, expiring) that is the credential for that one order's status — no sign-in required, so a customer can check their order straight from the email.

This is distinct from the signed-in order history under Customer accounts: order history needs a session and shows every order; the status link needs only the token and shows exactly one order, read-only.

All paths below are under /api/v1.

The read contract

GET /api/v1/public/orders/token/:token

The o token in the path is the credential. It's an opaque string — the prefix o immediately followed by 25 lowercase alphanumerics, no separator (o + [a-z0-9]{25}) — so don't construct or reformat it; pass through exactly what the email link carried. The call still requires x-organization-slug, and the token only resolves under the tenant it was minted for.

curl https://api.litecommerce.io/api/v1/public/orders/token/oa1b2c3d4e5f6g7h8j9k0m1n2p \
  -H "x-organization-slug: your-store"

It is a pure read — the token is never consumed and stays valid until it expires, so the customer can reopen the link. The projection is deliberately PII-free: order number, the two lifecycle states, line items by display name, the totals, timestamps, and the tenant's returnToStoreUrl (when configured) — and no customer name/email/addresses and no database ids. The emailed link is forwardable, so it must never unlock contact details or anything that could be used to enumerate orders.

What the projection carries:

  • orderNumber — the public ORG-YEAR-NNN number.
  • status / fulfillmentStatus — the two lifecycle states.
  • subtotalInCents / discountInCents / taxInCents / totalInCents — money in minor units.
  • items[] — name, quantity, unitPriceInCents, totalPriceInCents, by display name (no database ids).
  • createdAt / updatedAt — ISO timestamps.
  • returnToStoreUrl — the tenant's configured back-to-store link, or null.

Neutral 404 for every miss

Unknown, expired, revoked, malformed, and cross-tenant tokens all return the same neutral 404. The endpoint can't be used as an oracle for whether a token is valid, whether an order exists, or whether a token belongs to this tenant. Your status page should render one neutral "this link is invalid or has expired" state for any 404, and only distinguish a genuine transient error (5xx) as "try again."

Where the token comes from

The o token is minted at order-confirmation email time, not at order creation — the raw token is stamped into the emailed link and never persisted in plain text. The hosted litecheckout app renders this page at {tenant}.litecheckout.io/order/<token>/status; a BYO storefront can render its own page against the same endpoint.

Related