Payment opens one provision task and a pending subscription. Delivery completes the order, a cancelled claim reopens it, and renewal records the chosen term without taking anchor stock. Co-authored-by: Cursor <cursoragent@cursor.com>
4.0 KiB
Domain: Orders, Checkout, Fulfillment, Freight
Lifecycle
cart → checkout (one tx) → order per shop physical shipment flow
───────────────────────── ─────────────────────────
pending_payment ──pay──► paid ──first shipment──► fulfilling ──all shipped──► shipped
│ │
└──cancel──► cancelled delivered (all shipments) ──► completed
direct purchase (one non-physical SKU, cart untouched)
pending_payment ──pay──► paid ──claim provision task──► fulfilling ──deliver task──► completed
▲ │
└──── cancel provision task ───┘
renewal payment applies as paid ──► completed and extends the subscription
orders.fulfillment_kind is snapshotted from the product. Physical orders keep a shipping address. A new provisioned-service purchase stores contact (the buyer email) and fulfillment_details, leaves shipping_address null, and completes only when its provision task is delivered: the same transaction marks the task done, sets completed_at, and activates the subscription with the public access URL and region. Cancelling a claimed provision task returns the order to paid and opens a new pending task for the same item. The old /shop/orders/{id}/start-fulfilment and /deliver routes return 409. A renewal sets term_months to the chosen term and clears termination_marked_at. A renewal stores fulfillment_details.renew_subscription_id, skips the anchor stock decrement, and completes when payment is applied. Shipments, return-refund after-sales, coupons, threshold promotions, flash sales, group buying, and growth accrual do not apply to a service order. Every arrow is a guarded UPDATE … WHERE status = …; stale actions → 409.
Subscription status is separate: pending until delivery, then active, grace at end_at, suspended 15 days later, and a terminate task 30 days after suspension. Renewal is refused while a terminate task is open.
Checkout invariants (modules/order/service.rs)
One transaction per checkout: lock SKUs (FOR UPDATE in id order) → resolve
flash-sale activity pricing → per-shop coupon discount (server-computed,
client sends only coupon ids) → per-shop freight fee → insert order + items +
stock decrements → commit → clear cart. A direct purchase resolves one published non-physical SKU at quantity 1, does not read or clear the cart, hashes only that input for idempotency, and skips freight (fee 0, no template snapshot). Cart checkout drops any non-physical line before pricing. Orders are split per shop; each order
carries total_minor = subtotal − discount + shipping_fee_minor.
Snapshots make history immutable: order items keep unit_price_minor,
product_name, flash_sale_item_id, and the freight
freight_template_id/freight_pricing_method resolved at checkout. Later
template edits never touch past orders.
Freight (modules/freight/)
Templates are shop-scoped (own_shop): by_piece or by_weight (grams on
skus.weight_grams), first-unit + additional-unit fees with part-unit
round-up, always_free, free_threshold_minor, and region rules overriding
default fees by case-insensitive match against address region/city/country.
Resolution per line: product template → shop default → zero fee. Fees merge
per template group within a shop order and convert from the group's SKU
currency to the order currency.
POST /orders/shipping-quote is the read-only quote (normal prices only);
checkout recomputes authoritatively in the order transaction. Client-supplied
fees are never read.
Shipping companies are a dictionary (shipping_companies); shipments record
shipping_company_code validated against it.
Key files
See docs/code_index/order.md.