Retail & e-commerce — spec it like someone who's run a store

The SMB retail buyer already pays Shopify ($39–399/mo + 2.9%), BigCommerce, Wix, Ecwid, or WooCommerce. They are not naive — so the spec can't be either. A storefront that "has products and a cart" is table stakes; the value is in the parts those platforms do badly. Read this before writing the catalog/inventory/pricing/cart sections of any retail ARCH or PLAN doc.

1. Domain vocabulary (use these exact words)

• SKU vs variant — a variant is one buyable configuration (Red / Large); its SKU is the unique code that variant ships and is counted under. A "product" is the parent; you stock, price, and sell variants, not products.
• Multichannel / omnichannel — selling across several channels (own storefront, Amazon, eBay, in-store POS, Instagram). Omnichannel additionally means one inventory pool behind all of them. Channel-awareness is the whole game for SMB inventory.
• Reorder point — stock level that triggers a purchase order = (avg daily demand × lead time in days) + safety stock. Lead time = supplier days from order to receipt. Safety stock = buffer for demand/lead-time variance. Reordering without all three is wrong.
• COGS (cost of goods sold) and margin = (price − COGS) / price. Landed cost = unit cost + freight + duties + handling; margin must use landed cost, not invoice cost.
• ATS / available to sell = on-hand − allocated (reserved by open orders) − safety stock. Customers buy against ATS, never raw on-hand.
• Backorder vs preorder — backorder = out of stock now, will refill (sell against incoming PO). Preorder = not released yet, future availability date. Different fulfillment promises.
• Cart abandonment rate = 1 − (completed checkouts / carts created); industry ~70%.
• AOV (average order value) and conversion rate = orders / sessions. The two levers pricing/promotions move.
• Fulfillment — pick/pack/ship. Dropship = supplier ships direct, seller never holds stock (so "stock" is the supplier's ATS feed, not yours).
• MAP (minimum advertised price) — supplier-imposed price floor; a pricing rule must respect it or the seller loses the brand.

2. Non-obvious domain rules

• Shopify owns the storefront — don't fight it head-on. A me-too checkout loses. The wedge is the platforms' weak spots: multichannel inventory + reorder, and cart recovery. Spec the storefront as competent-and-owned, and put the differentiation in the other three.
• Variants explode combinatorially. options (Size × Color × Material) multiply: 5×8×3 = 120 variants per product. The data model, UI, and import flow must assume hundreds of variants per product, each with its own SKU / price / stock — not a flat product list.
• Inventory must be channel-aware. The same SKU is sold on storefront + Amazon + POS; stock must decrement across all and sync back, or you oversell. Single-channel inventory is the most common naive failure and the strongest wedge.
• Pricing rules interact with floors. A promotion or demand-based rule must clamp to a margin floor and MAP. A rule that can price below landed-cost margin is a bug, not a discount.

3. What a naive build gets wrong

• Products without a variant model — a flat product { price, stock } table. Breaks the instant the seller stocks two sizes. Variants are core, not an add-on.
• Single-channel inventory — stock that lives only in the storefront, no sync across Shopify / Amazon / POS. Guarantees overselling for any real SMB.
• Reorder without lead-time / safety-stock — "reorder when stock < 10" stocks out during the supplier lead time. Must use reorder-point math.
• Cart recovery that ignores suppression / consent — emailing/SMSing without consent, or after unsubscribe/purchase, is illegal (CAN-SPAM / TCPA / GDPR) and burns deliverability. Honor suppression + quiet hours.
• Pricing that ignores the margin floor — a promo engine that can sell below cost, or below MAP.

4. Must-model entities

Entity	Key fields
Product	id, title, option axes (e.g. Size, Color) — the parent
Variant	product_id, option values (Red/L), SKU, price, COGS/landed cost — one per option combo
InventoryLevel	variant_id, channel/location, on_hand, allocated, safety_stock → derive ATS
ReorderRule	variant_id, reorder_point, reorder_qty, lead_time_days, supplier
PricingRule	scope (variant/collection), trigger (demand/margin/schedule), action, margin_floor, MAP
AbandonedCart	cart_id, customer, line items, value, abandoned_at, recovery state, consent/suppression

The Variant option matrix and the channel-keyed InventoryLevel are the two that naive specs collapse — keep them explicit.

5. Per-product notes (wedge + the one domain thing)

• storefront (content) — catalog, checkout, themes; a store the seller owns. Wedge: owned channel + SEO (it must rank — see [[local-seo]]). The one thing: the Product→Variant model and clean indexable URLs. Don't out-engineer Shopify's checkout; match it and move on.
• inventory (crud) — track stock across channels, auto-reorder before stockout. This is the underserved-by-Shopify wedge. The one thing: channel-aware InventoryLevel + reorder-point math (lead time + safety stock). Get this right and the product justifies itself.
• pricing (dashboard) — rules-based pricing + promotions reacting to demand/margin. Wedge: margin-aware automation SMBs do by hand. The one thing: every rule clamps to margin floor + MAP.
• cart-recovery (crm) — win back abandoned carts via timed email/SMS. Wedge: recovering the ~70% that abandon. The one thing: consent + suppression + timing — defer the messaging mechanics to [[lifecycle-messaging]].

6. Compliance (light — defer the heavy parts)

• Sales tax nexus — economic nexus thresholds vary by US state (post-Wayfair); the seller may owe tax in states they've never shipped to. Note it in the spec; defer the actual calc/filing to billing. Don't hand-roll tax.
• Email / SMS consent — cart recovery needs prior consent (CAN-SPAM / TCPA / GDPR), honored unsubscribe, and quiet-hours/suppression. Defer the delivery + consent machinery to [[lifecycle-messaging]]; the spec just states the requirement.
• PCI — checkout uses Stripe-hosted elements so card data never touches our servers (SAQ-A scope). State that intent; defer the scope proof to pci-reviewer.

Output

When applied, contribute a Retail domain section to the ARCH/PLAN/DESIGN doc:

## Retail domain
- model: Product→Variant (option matrix, per-variant SKU/price/stock) · channel-aware InventoryLevel (ATS = on_hand − allocated − safety_stock)
- reorder: reorder_point = avg_demand × lead_time + safety_stock (not "< N")
- pricing: every rule clamps to margin_floor + MAP (margin on landed cost)
- cart-recovery: consent + suppression + timing → [[lifecycle-messaging]]
- wedge: multichannel inventory + reorder, cart recovery (don't fight Shopify's storefront/checkout)
- compliance: tax nexus → billing · consent → [[lifecycle-messaging]] · PCI Stripe-hosted (SAQ-A) → pci-reviewer
- migration: catalog/variant/stock import path → [[migration-ready-schema]]