Guest Checkout Module — Storefront

HTTP surface for guest (no-account) checkout — contact capture for an anonymous cart, a non-blocking "you already have an account" hint, and public order tracking after the order is placed. Delivered as a removable plugin built on better-auth's anonymous plugin: a guest is a throwaway anonymous user, so the core cart / place-order flow runs unchanged.

Source: api-modules/guest-checkout/src/controllers/store-guest-checkout.controller.ts, api-modules/guest-checkout/src/controllers/store-guest-order-lookup.controller.ts.

This is a customer-facing-only surface — no admin or vendor controller. Removing GuestCheckoutModule.forRoot() from app.module disables every endpoint below, the guest confirmation email, and the guest→account conversion. The better-auth POST /auth/sign-in/anonymous endpoint remains but is inert without this module.

The guest flow

1. Start a guest session — POST /auth/sign-in/anonymous (better-auth, not this module). This mints an anonymous user whose user.email is an unroutable temp address.
2. Build the cart — the standard store/cart endpoints, using the same x-cart-token handle.
3. Capture contact — POST /store/guest/contact stores the guest's real email (used for the confirmation + tracking link) against the active cart.
4. Place the order — the standard store/orders place-order flow, unchanged.
5. Confirmation — on order.placed, this module mints an unguessable lookup token, binds it to the contact, and emails a tokenized order-status link. (The default order-placed notification is suppressed for anonymous users, so this is the only confirmation a guest receives.)
6. Track — the guest opens the tokenized link (GET /store/guest/orders/:token) or uses the email + order-number form (POST /store/guest/orders/lookup).
7. (Optional) Convert — if the guest later signs up / signs in, better-auth links the anonymous account and this module re-keys their orders, addresses, and discount usage onto the real account before the anonymous user is deleted.

Conventions

Authentication

All controllers run BetterAuthGuard with @OptionalAuth() — a session is read when present but never mandated by the guard. The order-tracking endpoints are deliberately public so a guest can track without ever logging in.

Headers (contact endpoint)

Mirrors the cart/checkout controllers; forwarded to the cart layer verbatim:

Response envelope

{
  "data": <payload>,
  "message": "Success",
  "statusCode": 200
}

Error envelope

Neutral 404 on tracking

Both order-tracking endpoints raise the same 404 GUEST_ORDER_NOT_FOUND on any miss (unknown token, wrong email, unknown order number, email/order mismatch) so the endpoints can't be used to enumerate orders or probe which emails placed orders.

Domain types

GuestContactResponse — POST /store/guest/contact

type GuestContactResponse = {
  email: string;
  accountExists: boolean;   // non-blocking hint; never gates checkout
};

GuestAccountExistsResponse — GET /store/guest/account-exists

type GuestAccountExistsResponse = { exists: boolean };

Order detail

The two order-tracking endpoints return the order module's OrderResponse shape (see order.md) — the same payload an authenticated customer gets for their own order.

Endpoints

POST /store/guest/contact — Capture the guest's contact details

Requires an anonymous session (step 1 above). Resolves the active cart from x-cart-token (minting one if absent), stores the contact email/name/phone against that cart, and returns a non-blocking accountExists hint. The response sets x-cart-token.

Headers — x-cart-token (optional), x-platform (optional).

Body

{ "email": "guest@example.com", "name": "Jane Doe", "phone": "+15551234567" }

Response 200 — GuestContactResponse.

Errors

GET /store/guest/account-exists — Does a registered account use this email?

Non-blocking lookup driving the "you already have an account — log in to keep your orders together" hint. Never blocks guest checkout.

Query

Response 200 — GuestAccountExistsResponse.

POST /store/guest/orders/lookup — Track by email + order number

The WooCommerce/Magento-style guest tracking form.

Body

{ "email": "guest@example.com", "orderNumber": "SC-100245" }

Response 200 — OrderResponse (see order.md).

Errors

GET /store/guest/orders/:token — Track by private status-link token

The unguessable token (32 bytes of entropy → 43-char base64url) embedded in the confirmation email. Built into a URL of the form <STOREFRONT_URL>/order-status/<token>.

Path params

Response 200 — OrderResponse (see order.md).

Errors

Side effects (not direct HTTP)

These run off the event bus, not from a client call, but shape what the endpoints above return:

Related modules

• auth — the better-auth anonymous plugin mints the guest session; the onLinkAccount hook drives conversion. POST /auth/sign-in/anonymous is the prerequisite for POST /store/guest/contact.
• cart — POST /store/guest/contact resolves the active cart via CartService using the same x-cart-token / x-platform handles as the cart endpoints. See cart.md.
• order — order tracking returns the order module's OrderResponse; the confirmation flow listens on order.placed. See order.md.
• notifications — the default order-placed notification is suppressed for anonymous users (recipient resolver), leaving this module's guest confirmation email as the sole notice.