Vertical Retail

---
name: vertical-retail
description: Retail & e-commerce domain knowledge for SMB storefront products (storefront, inventory, pricing, cart-recovery). Codifies the vocabulary (SKU vs variant, reorder point, COGS/margin, ATS, AOV), the non-obvious rules (Shopify owns the storefront — don't fight it head-on; the wedge is multichannel inventory + reorder and cart recovery), the must-model entities (Product→Variants matrix, channel-aware InventoryLevel, ReorderRule, PricingRule, AbandonedCart), and what a naive build gets wrong (no variant model, single-channel inventory, reorder without lead-time/safety-stock). Applied by architect/pm during spec authoring so they aren't naive about retail; checked implicitly by pci-reviewer + cms-reviewer.
when_to_use: |
  Apply when architect or pm is speccing a retail / e-commerce product:
  - storefront / inventory / pricing / cart-recovery for an SMB seller
  - any catalog, checkout, stock-tracking, promotion, or abandoned-cart feature
  Do NOT apply to non-commerce verticals, or to heavy payments/tax work (defer those to pci-reviewer / billing).
effort: low
allowed-tools: Read, Write, Grep, Glob
paths:
  - "docs/architecture/**"
  - "docs/plans/**"
  - "docs/design/**"
---

# 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]]
```