Buying and selling

From cart to confirmed order

What happens when a buyer chooses products, checks out, pays, and gets an order.

Last updated 2026-07-255 sections

Normalized cart

One active cart exists per buyer, merchant, and channel. Cart items reference exact variants and keep quantity, title, price, and weight snapshots. Each mutation increments a version and recomputes subtotal/currency. Buyer ownership and merchant/store consistency are checked before any write.

Native cart to checkout

sequenceDiagram
  participant B as Buyer
  participant W as WhatsApp
  participant D as Domain
  participant DB as PostgreSQL
  B->>W: Native same-shop cart
  W->>D: Replace active cart
  D->>DB: Versioned cart and audit
  W-->>B: Request address
  B->>W: Address Flow
  W->>D: Quote aggregate weight
  D-->>W: Current quote with expiry
  W-->>B: Canonical order summary
  B->>W: Action-specific confirmation
  W->>D: Revalidate every item and quote
  D->>DB: Address, order, items, reservations, cart conversion
  D->>DB: Queue payment initialization

If the diagram does not render, its Mermaid source remains readable above.

Cross-seller or cross-shop carts fail without writes. Confirmation binds the exact cart version, address, delivery quote, total, currency, and expiry.

Inventory and order state

stateDiagram-v2
  [*] --> awaiting_payment
  awaiting_payment --> paid: provider confirmation
  awaiting_payment --> cancelled: buyer cancellation
  paid --> accepted
  accepted --> preparing
  preparing --> ready_for_dispatch
  ready_for_dispatch --> dispatched
  dispatched --> in_transit
  in_transit --> delivered
  delivered --> completed
  paid --> disputed
  paid --> refund_requested
  refund_requested --> refunded

If the diagram does not render, its Mermaid source remains readable above.

Inventory changes use an append-only ledger. Reservation, order items, totals, and cart conversion commit atomically. Cancellation releases reserved stock once. Dispatch and return paths add new ledger entries rather than editing history.

Concurrency and recovery

Advisory locks and guarded updates prevent overselling and duplicate conversion. Revalidation catches changed price, stock, ownership, address, quote, or cart version before consequential writes. A stale summary is invalidated and must be replaced with current facts.

src/orders.ts
src/catalog.ts
src/pending-actions.ts
db/migrations/030_goals_tools_cart.sql
test/orders.test.ts
test/phase3.e2e.test.ts

Guarded post-purchase and retention paths

Six default-off flags independently guard seller attention, buyer post-purchase controls, reorder, saved intents, alerts, and personalisation. Seller attention is a zero-write projection of current support, dispute, shipment, order, consent, and inventory records. Address and delivery-window requests create order-bound support subjects and never modify a courier booking.

Reorder revalidates every original seller, store, product, variant, quantity, price, and stock fact. Unavailable items and changed prices require explicit buyer choices. Success creates only one active cart; it reserves no inventory, creates no order or payment, and requires a fresh quote plus the normal confirmation path.

Saved-intent alert delivery remains blocked until privacy fulfilment, purpose consent, exact template approval, exact provider-target certification, opt-out, and reconciliation drills pass.

docs/NEO_RETENTION_PLAN.md
src/seller-attention.ts
src/buyer-retention.ts
src/saved-intents.ts
src/retention-notifications.ts
db/migrations/066_retention_foundations.sql
db/migrations/067_saved_intents_notifications.sql
test/retention.test.ts