Stock Status Badge

Free — GPL coresize Splanned, not built

Generated from docs/plan/core/stock-status-badge/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A core-free inventory feature that displays stock status (in-stock, low-stock, out-of-stock) on product listings and detail pages. Helps customers make purchase decisions early and reduces checkout abandonment from ‘item not available’ surprises.

The problem

Customers browse my product listing and see no stock status, so they click through to detail page only to find ‘out of stock’. They get frustrated and leave. I need a clear indicator before they click.

What it does

• Stock status badge on listing: displays ‘In Stock’, ‘Low Stock’, or ‘Out of Stock’ based on current inventory
• Low-stock threshold setting: merchant configures qty (default 5 units) below which ‘Low Stock’ displays
• Product detail page status: prominent display of stock status and available qty
• Status color coding: green (in-stock), orange (low), red (out-of-stock) in storefront UI
• Dynamic update: status refreshes when inventory changes (real-time or on product detail reload)
• Configurable threshold per product: override global setting if needed (e.g., high-demand item threshold = 20)
• Stock status API: GET /api/products/:id/stock-status returns { status: ‘in-stock’|‘low’|‘out-of-stock’, available_qty: int, threshold_qty: int }
• Admin setting for global low-stock threshold: single input in settings UI
• Backorder flag (optional): if product allows backorder, status shows ‘Out of Stock – Backorder Available’ instead of blocking purchase

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Inventory reservations or holds — checkout process handles order holds; status badge shows current on-hand only
• Back-in-stock notifications — separate paid feature; status badge does not offer signup
• Per-warehouse or per-location visibility — MSI (multi-source inventory) is separate module; badge shows total qty
• Product alerts or notifications for staff — this is customer-facing only; staff alerts are in forecasting module

Data model

None (uses existing inventory + settings). Settings table extended with ‘inventory_low_stock_threshold_qty’ (integer, default 5).

API

• GET /api/products/:id/stock-status

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Single input field in Inventory Settings section: ‘Low Stock Threshold (units)’ default 5. Per-product override optional field in product editor.

The seam — why this is core

Core owns the stock-status interface and display logic. No paid seam — this is core infrastructure for storefront confidence.

Core owns the interface + honest status indicator; storefront components are infrastructure, not a per-country obligation or credential.

Dependencies

• product module (SKU)
• inventory module (qty tracking)
• settings system (threshold storage)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• GET /api/products/:id/stock-status returns status=‘out-of-stock’ when qty=0
• status=‘low-stock’ when 0 < qty <= threshold
• status=‘in-stock’ when qty > threshold
• Threshold is configurable setting; default is 5
• Per-product override, if set, overrides global threshold
• Status updates within 1 second of inventory change (if using pub-sub) or on reload (if pull-based)

Risks

Cached status shows stale qty (out-of-stock badge when actually 1 unit remains); threshold not applied consistently across all storage drivers; race condition: inventory decrements to 0 while customer views ‘in-stock’ badge; per-product override not applied to all variants.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.