E-commerce Cart and Checkout

Pathrule4 Rules • 2 Memories • 1 Skill

Checkout coordinates several authorities that change independently: products and promotions, taxes and shipping, inventory, customer identity, payment state, order state, and fulfillment systems. This pattern constrains server-side pricing, inventory reservation, idempotent order creation, and payment-order reconciliation; it records cart and checkout state ownership and provides a release verification workflow. It differs from subscription billing by focusing on one-time cart and order state, and from Stripe-specific guidance by preserving provider-independent commerce invariants.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

verify-checkout-state-machine

src/

commerce/

Calculate payable totals from server-owned inputs

Reserve scarce inventory through one atomic transition

Create one order per logical checkout

The cart is editable intent while the order is an immutable snapshot

Checkout is a recoverable state machine

payments/

Advance order state from authoritative payment evidence

Rules

Calculate payable totals from server-owned inputs/src/commercehighstrictResolve catalog version, price, currency, promotion, tax, shipping, and rounding on the server for every checkout attempt.

1	The client displays a proposal, not an authority. Product prices, eligibility, stock, tax, shipping, and exchange rules can change between cart editing and payment creation.
2
3	- Accept stable product, variant, quantity, and promotion identifiers from the client, then load current authorized commerce data on the server.
4	- Calculate money in integer minor units or an exact decimal representation with one documented rounding policy per currency and tax boundary.
5	- Return a priced checkout snapshot with version and expiry so the UI can explain changes instead of silently charging a different total.
6	- Store the exact line, discount, tax, shipping, currency, and total breakdown accepted for the order rather than recomputing historical orders from the current catalog.
7
8	See /src/payments for the adjacent decision or procedure that completes this constraint.

Reserve scarce inventory through one atomic transition/src/commercehighstrictCheck availability and create a bounded reservation together, then commit, release, or expire it by stable checkout identity.

1	Reading stock and decrementing later lets concurrent checkouts each observe the same unit. Holding inventory forever on abandoned payment attempts creates a different availability failure.
2
3	- Perform availability check and reservation update in one database transaction or atomic inventory service operation.
4	- Give the reservation a checkout or order identity, quantity, expiry, and status so retries return the same reservation.
5	- Commit the reservation when authoritative payment and order policy allow fulfillment; release it on terminal failure or cancellation.
6	- Expire abandoned reservations through idempotent scheduled work and reconcile inventory records rather than deleting evidence blindly.
7
8	See /tests/checkout for the adjacent decision or procedure that completes this constraint.

Create one order per logical checkout/src/commercehighstrictUse a stable checkout idempotency key and persist order state before redirecting or calling payment infrastructure.

1	Browser retries, double clicks, gateway timeouts, and payment redirects can repeat checkout creation. A fresh order ID on every request turns one intent into several payable records.
2
3	- Create the logical checkout identity before external payment calls and enforce uniqueness at the server boundary.
4	- Persist the order and priced snapshot in a pending state, then reuse them when the same identity returns.
5	- Propagate the same identity into payment-provider idempotency and metadata fields without using mutable or personal values as keys.
6	- Disable duplicate UI submission for usability, but rely on database and provider idempotency for correctness.
7
8	See /src/payments for the adjacent decision or procedure that completes this constraint.

Advance order state from authoritative payment evidence/src/paymentshighstrictVerify provider events or server-side status and make state transitions monotonic before fulfillment begins.

1	A success page, client callback, or redirect parameter can be forged, replayed, abandoned, or reached before the provider's durable result. Fulfillment needs server-verified payment state.
2
3	- Verify event signature and account context or retrieve payment state through authenticated server APIs before changing the order.
4	- Handle duplicate and out-of-order events idempotently and reject transitions that would move a terminal order backward.
5	- Store provider payment identity, amount, currency, capture state, and event identity needed for reconciliation without retaining prohibited payment data.
6	- Start fulfillment through a durable outbox or job after the paid transition commits, not directly inside a webhook response.
7
8	See /src/commerce for the adjacent decision or procedure that completes this constraint.

Memories

The cart is editable intent while the order is an immutable snapshot/src/commerceLet carts change freely, but copy accepted commercial terms into an order that later catalog edits cannot rewrite.

1	A cart belongs to an active shopping session and may hold stale or unavailable choices. An order is a financial and fulfillment record whose line identity and totals must remain understandable after products, names, or prices change.
2
3	- Store stable product and variant references in the cart and reprice before checkout rather than treating cached display values as current.
4	- Copy customer-facing description, quantity, unit price, discounts, tax, shipping, currency, and total into the accepted order.
5	- Append order adjustments, refunds, cancellations, and fulfillment events instead of mutating history to resemble the latest catalog.
6	- Merge anonymous and authenticated carts through an explicit product policy that resolves duplicates, quantities, ownership, and expired items.
7
8	See /src/payments for the rule or workflow that puts this decision into practice.

Checkout is a recoverable state machine/src/commercePersist progress and authoritative identifiers so refresh, return, authentication, challenge, and provider delay resume one checkout.

1	Checkout spans browser navigation and external systems. Treating it as one request loses state when the user authenticates, returns from payment, closes a tab, or waits for asynchronous confirmation.
2
3	- Model pricing, reservation, order creation, payment pending, challenge, paid, failed, expired, and cancelled states with allowed transitions.
4	- Store only the minimum browser state needed to resume and recover authoritative status from the server by checkout identity.
5	- Make return routes safe to reload and revisit; they query state instead of repeating payment or order creation.
6	- Surface pending and recoverable failures honestly, including a path to retry payment without creating a second order or reservation.
7
8	See /tests/checkout for the rule or workflow that puts this decision into practice.

Skills

verify-checkout-state-machine/rootExercise pricing, stock contention, retries, payment outcomes, browser returns, events, and fulfillment as one checkout flow.

1	---
2	name: verify-checkout-state-machine
3	description: Verify an e-commerce checkout change before accepting production payments.
4	---
5
6	# Verify Checkout State Machine
7
8	Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result.
9
10	1. Test stale prices, invalid promotions, tax and shipping changes, currency rounding, missing products, and quantities at inventory boundaries.
11	2. Run concurrent checkouts for the last units and prove reservations prevent oversell, expire safely, and remain idempotent on retry.
12	3. Repeat order and payment creation through double click, timeout, reload, back navigation, and duplicate client requests with the same logical key.
13	4. Replay valid, duplicate, out-of-order, delayed, malformed, wrong-account, wrong-amount, authorized, captured, failed, and cancelled payment evidence.
14	5. Verify fulfillment starts once after committed paid state, and reconcile every order against payment and inventory records after induced partial failures.
15
16	## Exit criteria
17
18	The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.

Why this pattern

AI agents often trust client totals, decrement inventory before payment without expiry, create duplicate orders on retry, or mark an order paid from the browser redirect alone.

Built for Commerce teams operating carts, physical or digital inventory, one-time payments, and fulfillment.

Keeps your assistant from:

Charging a client-manipulated price or discount
Overselling stock through concurrent checkouts
Creating several orders from one checkout retry
Fulfilling an order before authoritative payment confirmation

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25