# Inventory Urgency — Reasoning & Recommendations
**Companion to:** [feature-design-guidelines.md](feature-design-guidelines.md), [saved-cart-concepts.md](saved-cart-concepts.md)
**Live preview:** PDP at https://demo.thecxlabs.com/v2/pdp.html · PLP at https://demo.thecxlabs.com/v2/plp.html · Cart at https://demo.thecxlabs.com/v2/cart.html
**Date:** May 2026
This document explains the inventory-urgency pattern across PDP, PLP, cart, and account surfaces — when to show "Only 3 left in stock," how it differs from manipulative urgency theater, and how BC Stencil natively powers it.
---
## TL;DR
When inventory drops to **≤10 units**, show the **exact count** ("Only 3 left in stock") in an amber-tinted badge. Above the threshold, show "In stock" with no count. Out-of-stock items get an "Out of stock — notify me when back" affordance. The pattern is honest urgency — derived from real inventory data, not a synthetic countdown.
Native BC Stencil powers all of this via `inventory_level` + `low_stock_level` product fields. No app or replatform needed.
| Phase | Surface | Effort |
|---|---|---|
| **Phase 1** _(Pilot)_ | PDP hero pill, PLP card badge, cart row pill, account fleet snapshot. Threshold = 10 units default. | **Low** — Stencil native field + theme template edit |
| **Phase 2** _(Iterate)_ | Per-category thresholds (paper bags ≤24, chemicals ≤6). Email notification when an item the user viewed drops below threshold. | Medium — admin config + customer-attribute join |
| **Phase 3** _(Future)_ | Predictive "stock running low" before crossing threshold based on velocity (last 30-day sell-through rate). | Higher — typically a marketplace app or custom analytics; Catalyst-replatform candidate |
---
## Current state
The current PDP shows "In Stock" or no badge at all. PLP cards show fuzzy "IN STOCK / LOW STOCK / OUT OF STOCK" pills without counts. No surface anywhere shows the *count*. Buyers can't tell whether "Low stock" means 3 units or 30.
Why it matters: B2B buyers managing recurring procurement actively *want* the count. A fleet manager ordering for 3 sites knows they need 24 brushes — if the listing shows "Only 8 left," they decide whether to wait for restock or order an alternate now. Hiding the count makes the decision blind.
The cart already has limited urgency demonstrated (the saved-for-later battery shows "3 left in stock"); the rest of the surfaces need to catch up.
---
## References
### Amazon — the canonical pattern
"Only N left in stock — order soon" is Amazon's exact wording. Above threshold: "In Stock." Below threshold and falling fast: "Only N left in stock (more on the way)." Threshold appears to be ~10–20 depending on category.
### Grainger
Shows exact count when low: "Only 6 available." Cart shows backorder ETA inline. No "running low" predictive.
### McMaster-Carr
Doesn't show urgency. Their model: order it, McMaster will tell you in checkout if it's not available. Engineers know they're going to order what they need regardless.
### HD Supply
Quantity available shown on PDP for B2B customers. Often shows multi-warehouse availability ("Atlanta: 8 in stock; Dallas: 22 in stock") — a B2B-specific extension worth considering for Phase 2.
### Anti-pattern: synthetic urgency
"23 people viewing this right now" / "Last one!" / countdown clocks. Avoid. These erode trust in B2B contexts. Honest inventory urgency (real count, real threshold) is the win.
---
## What BC Stencil gives us
- **`product.inventory_level`** — current on-hand quantity per product or per variant. Native field.
- **`product.inventory_warning_level`** (admin: "Low Stock Notification Level") — threshold the merchant configures per product. When `inventory_level <= inventory_warning_level`, the product is in the low-stock state. Default applies if not configured per-SKU.
- **`product.inventory_tracking`** — "none" / "product" / "variant." Determines which level to read.
- **Stencil templates** — `{{#if product.inventory_level}}` and `{{#if product.is_low_stock}}` are exposed in product, card, and cart templates.
- **`/v3/catalog/products/{product_id}`** API exposes all three for programmatic config.
**Sources:** [BC Help — Inventory Settings](https://support.bigcommerce.com/s/article/Inventory-Settings), [BC Dev — Catalog Products](https://developer.bigcommerce.com/docs/rest-management/catalog/products), [BC Stencil — product variables](https://developer.bigcommerce.com/docs/storefront/stencil/themes/product).
---
## Stencil limitations
- **No native multi-warehouse inventory display.** BC stores a single `inventory_level` per product/variant. If USA Clean ships from 3 warehouses (Columbus / Texas / California — per the announcement bar), the storefront sees only the aggregate, not per-warehouse. The HD-Supply-style "Atlanta: 8 · Dallas: 22" pattern requires a custom field set or an app (Phase 2).
- **No predictive "stock running low" before threshold.** Stencil only reads the current count; it doesn't have a velocity API. Phase 3 would either query a separate analytics pipeline or move the logic into Catalyst.
- **Notify-me ("email me when back in stock") is partial.** BC has a "Notify When Back" link out of the box but emails go through the merchant's email system; the notification UI is basic. Most stores swap in a wishlist or back-in-stock app for the customer-facing piece.
- **Per-category threshold defaults.** The threshold is per-SKU, not per-category. Phase 2 needs admin automation (bulk-update via API or sheet import) to apply category-specific defaults like "all paper bag SKUs use threshold 24."
---
## App marketplace shortlist
| App | What it does | Worth it now? |
|---|---|:---:|
| **(Native) Inventory + warning level** | Built into BC core. | ✅ Use this. |
| **[Back in Stock by SiteSphere](https://www.bigcommerce.com/apps/back-in-stock/)** | Email + SMS notification when items return to stock. Better customer UI than native. | Maybe — useful when out-of-stock SKUs are common. |
| **[Stock Insights / Inventory Reports](https://www.bigcommerce.com/apps/category/reporting-analytics/)** | Velocity analytics by SKU; predictive low-stock alerts. | Phase 3 candidate — when merchandising team is staffed enough to act on alerts. |
| **Generic urgency apps** | "23 viewing now" / countdown clocks / fake stock numbers. | ❌ Skip — anti-pattern, erodes B2B trust. |
---
## Caster impact
**Existing `.stock-badge` primitive** (already in Caster) gets new usage convention:
- `stock-in` → "In stock" (above threshold, no count)
- `stock-low` → "Only N left" (≤10, with exact count)
- `stock-out` → "Out of stock" (zero)
- `stock-back` → "Backorder · ships {date}" (existing — for items with vendor ETA)
**No new tokens or components required.** The convention update is purely content/copy and threshold logic.
**Downstream impact:**
- PLP cards adopt the new copy convention (`In stock` not `IN STOCK`, `Only 3 left` not `LOW STOCK`).
- PDP related-items grid + bundle alt-options use the same convention.
- Cart row pill (`cart-row__pill--low`) already follows the pattern.
- Account dashboard fleet snapshot shows "Service due in 12 days" (already in this style); inventory urgency on equipment is N/A since machines aren't catalog SKUs.
---
## Phased recommendation
### Phase 1 — Apply default threshold of 10 across the catalog
Set `inventory_warning_level = 10` for all SKUs not individually configured. Theme template renders the "Only N left" badge wherever `inventory_level <= inventory_warning_level && inventory_level > 0`. Out-of-stock shows "Out of stock — notify me when back."
**What "winning" looks like:** measurable conversion lift on low-stock PDPs (the urgency message converts), no measurable bounce-rate increase (the message isn't perceived as pressure), and a tightening of the gap between order placement and stock-out events (buyers are reacting to the signal).
### Phase 2 — Category-specific thresholds + back-in-stock notifications
Different categories sell at different velocities. Paper bags sell 100/day — a threshold of 10 means "Only 10 left" appears every other week. Threshold should be higher (24+). Chemicals sell slower; threshold 6 is realistic. Batteries sell intermittently; threshold 3.
**Trigger:** when merch has 1-2 months of Phase 1 data showing where the threshold either fires too often (paper bags) or too rarely (specialty items). Bulk-update via admin script keyed on category.
Also Phase 2: replace the native "notify me when back" with [Back in Stock by SiteSphere] (or similar) for SMS notification — high-value for B2B fleet managers.
### Phase 3 — Velocity-based predictive low-stock
"Running low" before crossing threshold. Based on 30-day sell-through rate: if current stock / daily velocity < 7 days, show "Stock running low — typically ships within a week" even when count is above the static threshold.
Also surface **multi-warehouse availability** if USA Clean's WMS exposes per-warehouse counts: "Columbus: 8 · Texas: 0 · California: 12" for distributed buyers who care about delivery distance.
**Trigger:** Phase 2 data shows specific SKUs that stock-out unpredictably; merch + ops want forward-looking signal.
---
## Implementation notes
### Stencil theme edits (Phase 1)
1. **PDP hero pills row** — render the stock pill via:
```handlebars
{{#if product.inventory_level}}
{{#if product.is_low_stock}}
Only {{product.inventory_level}} left
{{else}}
In stock
{{/if}}
{{else}}
Out of stock — notify me
{{/if}}
```
2. **PLP card** — same logic in `templates/components/products/card.html`.
3. **Cart row** — already supports `cart-row__pill--low`; map low-stock state to that variant.
4. **Notify-me CTA** — extend the BC native "Notify When Back" with a friendlier link inside the stock-out badge.
### Accessibility
- Stock state is **conveyed by text, not color alone**. The "Only 3 left" text + amber background + warning-icon-dot pattern (already in the `.cart-row__pill--low`) ensures screen readers + colorblind users get the same signal.
- The count is announced inline: a screen reader reads "Only 3 left, in stock" — meaningful.
- When the count updates live (a buyer adds 5 to cart, stock drops from 10 to 5), the badge updates with `aria-live="polite"` so the screen reader announces "Now only 5 left." Avoid `aria-live="assertive"` — pushy.
### Analytics
- Conversion delta on PDPs in low-stock state vs. above-threshold.
- Bounce rate / time-on-page differential — confirm the message isn't perceived as pressure.
- Back-in-stock email opt-in rate from out-of-stock state.
- Velocity differential pre-launch vs. post-launch on low-stock SKUs (does urgency accelerate sell-through, or does it stable-out?).
---
## Catalyst / replatform candidacy
**Phase 1 + 2 ship well in Stencil.** Native fields + template logic + admin scripts. No friction.
**Phase 3 is Catalyst territory.** Velocity-based predictive low-stock requires querying analytics on every PDP render. Stencil can do it via API calls in the template (slow, expensive) or pre-compute and cache via a custom field (stale, manual). Catalyst's server-rendered React makes this clean — call the velocity service on PDP load, cache server-side, render.
Multi-warehouse availability is similar — a Stencil page can iterate a `warehouse_inventory` custom field, but the UX of "show me the closest warehouse with stock" is a Catalyst sweet spot.
---
## Sources
- [BC Help — Inventory Settings](https://support.bigcommerce.com/s/article/Inventory-Settings)
- [BC Dev — Catalog Products API](https://developer.bigcommerce.com/docs/rest-management/catalog/products)
- [BC Stencil — product template variables](https://developer.bigcommerce.com/docs/storefront/stencil/themes/product)
- [BC Help — Notify When Back in Stock](https://support.bigcommerce.com/s/article/Notify-When-Back-in-Stock)
- [Back in Stock by SiteSphere](https://www.bigcommerce.com/apps/back-in-stock/)
- [Amazon — "Only N left in stock" pattern reference](https://www.amazon.com/)
- [Baymard — inventory display research](https://baymard.com/blog)
- [feature-design-guidelines.md](feature-design-guidelines.md) — operating manual
- [saved-cart-concepts.md](saved-cart-concepts.md) — back-in-stock + saved-for-later overlap