Guest Checkout

01Requirements

Shoppers must be able to complete a purchase providing only an email address, shipping details, and payment, with no account creation before or during checkout. Guest orders remain fully trackable without a login, and a guest can promote their order into an account in a single post-purchase step. The business goal is recovering the checkout conversion currently lost at the sign-up wall, which the analysis identifies as most acute on mobile.

Assumption: returning shoppers who have an account but are not signed in may also check out as guests. The ask does not specify this; it is stated here so a reviewer can confirm or correct it.

02Entities

Order and Cart already exist in checkout-service and are extended, not forked. GuestSession and OrderAccessToken are new.

classDiagram
direction TB
class GuestSession {
  +id: uuid
  +email: string
  +createdAt: timestamp
  +expiresAt: timestamp  %% 30 days
}
class Order {
  +shopperId: uuid?        %% now nullable
  +guestSessionId: uuid?   %% new, exactly one owner
}
class OrderAccessToken {
  +orderId: uuid
  +tokenHash: string
  +expiresAt: timestamp
}
class Shopper {
  <<existing>>
}
GuestSession "1" --> "0..*" Order : owns
Order "1" --> "0..1" OrderAccessToken : tracked by
Shopper "1" --> "0..*" Order : owns

03Approach

1. Guest identity as a short-lived session, not a shadow account:

• A GuestSession keyed by email is created when guest checkout starts and expires after 30 days. No password, no account row, so there is no half-registered account state to clean up later.
• Post-purchase conversion (AC-3) promotes guest orders to the new account by verified email match, never by token possession.

2. Technical implementation in checkout-service:

• Extend the existing POST /checkout path to accept a guest session: shopperId becomes nullable on Order with a new guestSessionId, and a database constraint enforces exactly one owner.
• Order tracking links (AC-2) use signed, single-purpose access tokens scoped to one order, stored hashed, expiring with the session. The token grants read access to that order only, never to an account.
• Payment reuses the existing Stripe Elements tokenization path unchanged. The guest flow introduces no new payment surface.

3. Business rules:

• Guest checkout is rate-limited per email and IP to blunt card-testing abuse, mirroring the limits already applied to registered checkout.
• Checkout analytics events carry checkout_mode: guest or registered (AC-4), so conversion is comparable between the two paths.

04Structure

checkout-service is a TypeScript and Express service backed by PostgreSQL. The change adds two focused components and extends one; nothing else in the service moves.

Component relationships

• CheckoutController (extended): accepts guest or registered checkout and routes ownership accordingly.
• GuestSessionRepository (new): creates and expires guest sessions.
• OrderAccessTokenService (new): issues and verifies tracking tokens.
• ConversionService (new): promotes guest orders to a newly created account after email verification.
• OrderRepository, PaymentGateway (unchanged): reused as they exist today.

Dependencies

• CheckoutController depends on GuestSessionRepository and the existing OrderRepository and PaymentGateway.
• ConversionService depends on the accounts service email-verification flow, which already exists.
• OrderAccessTokenService is used by the order-tracking endpoint and the confirmation-email composer.

05Operations

06Norms

• API errors follow problem+json (org norm): both new endpoints return RFC 7807 problem details, matching the rest of checkout-service.
• Reversible migrations (org norm): both schema changes ship with tested down migrations.
• Checkout changes behind a feature flag (project norm): the entire guest path sits behind the guest_checkout flag, default off, so rollout is gradual and reversible.

07Safeguards

• PCI scope must not expand: card data never touches our servers. This blueprint reuses the existing Stripe Elements tokenization; no new component receives, logs, or stores card data. Any change to payment capture is out of bounds for this feature.
• No PII in logs or analytics: guest emails are hashed in analytics events, and tracking tokens are never logged.