stockout-prevention

---
name: stockout-prevention
description: >-
  Monitors FBA inventory health, identifies stockout risks from sales velocity,
  and orchestrates prevention actions — primarily inbound-shipment gap analysis and
  restocking. Triggers on: inventory check, stockout risk, FBA stock levels,
  days of cover, days of supply, replenishment, "am I going to run out". Do NOT use
  for: catalog management, new product listings, advertising, or order fulfillment.
version: 1.0.0
license: Apache-2.0
metadata:
  author: Amazon Selling Partner
  persona: Maya (non-technical FBA seller)
  pattern: Pipeline + Inversion
  tags: [sp-api, inventory, fba, stockout, pricing]
  platforms: [claude-desktop, aws-quick]
  apis: [fba-inventory, sales, fba-inbound, listings]
---

# Stockout Prevention Skill

## Description

Helps a Fulfilled-by-Amazon seller stay ahead of stockouts. It pulls current FBA
inventory, derives sales velocity, computes **days of cover** per SKU, checks
whether inbound shipments arrive in time, and proposes preventive actions. Write
actions (e.g. price changes) are **always drafted for the seller's approval** —
never executed silently.

## When to use this skill

Use when the seller asks anything about inventory health, running out of stock,
replenishment timing, or "what should I prioritize" for their FBA stock. Do not
use for listing content, advertising, or order management.

## Tools this skill orchestrates

All are SP-API MCP tools served via the Amazon Selling Partner Connector (the `amazon-selling-partner` MCP server):

| Step | Tool | Purpose |
|------|------|---------|
| Inventory | `fbaInventory_getInventorySummaries` | Current fulfillable units per SKU |
| Velocity | `sales_getOrderMetrics` | Units sold over a window (per SKU when possible) |
| Inbound | `fbaInbound_listInboundPlans` | In-transit shipments + ETAs |
| Action | `listings_patchListingsItem` | Draft a price change (VALIDATION_PREVIEW first) |

> Every call needs `entityId` (the seller's merchant id) and `marketplaceIds`
> (e.g. `ATVPDKIKX0DER` for US). If you don't know the entityId, ask the seller once
> and reuse it for the session.

## Workflow (Pipeline + Inversion — ask before acting)

### Step 1 — Assess inventory
Call `fbaInventory_getInventorySummaries` (granularityType `Marketplace`).
Record `sellerSku`, `productName`, and `fulfillableQuantity` for each SKU.

### Step 2 — Measure velocity
For each SKU with meaningful stock, call `sales_getOrderMetrics` over the **last 30
days** (`granularity: Total`, pass the `sku`). Compute:

```
avg_daily_units = unitCount / 30
days_of_cover   = fulfillableQuantity / avg_daily_units
```

### Step 3 — Classify risk
- **CRITICAL** — days_of_cover < 7
- **WARNING** — 7 ≤ days_of_cover < 21
- **HEALTHY** — days_of_cover ≥ 21 (do **not** flag these; say they look fine)

> **Reconciling with Amazon's canonical rule.** Amazon's own analysis rule is *days of
> supply < 14 → at risk*. These bands are intentionally more conservative: 7–14 is the
> canonical at-risk range, and 14–21 is an *early-warning* buffer this skill adds so a
> fast-moving SKU is caught before it crosses 14. For a SKU in the 14–21 range, say it is
> **approaching** risk — not yet at-risk by Amazon's rule — rather than implying it already
> breached the threshold.

Present a short table: SKU · fulfillable · ~daily sales · days of cover · status.

### Step 3b — Visualize the risk (render a chart artifact)
After the table, **create a visual artifact** so the seller can see the risk at a glance.
Render an HTML/JS artifact (a single self-contained file) with a **days-of-cover bar chart**:
- one bar per SKU, height = days of cover;
- color each bar by status — **red = CRITICAL (<7)**, **amber = WARNING (7–21)**, **green = HEALTHY (≥21)**;
- draw a dashed threshold line at 7 and 21 days; label each bar with the SKU and its day count.
Keep it clean and legible (large fonts, title "Days of Cover by SKU"). Use inline SVG or a
lightweight chart approach — no external network calls.

### Step 4 — Check the inbound pipeline (only for flagged SKUs)
Call `fbaInbound_listInboundPlans`. For each flagged SKU, find any in-transit
shipment containing it and read its `estimatedDeliveryWindow`. Compute the **gap**:

```
stockout_date    = today + days_of_cover
shipment_arrives = estimatedDeliveryWindow.start
gap_days         = shipment_arrives - stockout_date   (positive = will stock out first)
```

Call this out explicitly: "You'll run out ~N days **before** the next shipment lands."

### Step 4b — Visualize the gap (render a timeline artifact)
For the most critical SKU, **create a second visual artifact**: a horizontal **timeline**
showing **today**, the **projected stockout date**, and the **shipment arrival window** —
with the at-risk gap between stockout and arrival shaded red and labeled
"~N days out of stock". Title it "Stockout vs. Inbound Shipment". Self-contained, no network calls.

### Step 5 — Recommend options (for CRITICAL SKUs with a gap)
Offer concrete choices, each with its trade-off. Lead with the actions Amazon's own
inventory guidance points to. **Do not raise pricing as an option at all** — this skill
gives no pricing advice in either direction (see Step 6 if the seller names a price).
- **A. Get more units in, sooner** — expedite an existing inbound shipment or create a new
  one so stock lands before the run-out date (this is where the
  [fba-inbound-management](../fba-inbound-management/SKILL.md) skill takes over). This is the
  primary lever.
- **B. Accept the stockout and plan the recovery** — note the cost (lost sales, BSR/rank
  recovery, and that running very lean can trigger the **low-inventory-level fee**), and line
  up the restock so it doesn't repeat.

Then **ask the seller what else they'd like to explore** rather than steering them:
> "Would you like to look at anything else — for example some quick market research on
> demand, competing offers, or seasonality for this SKU — before deciding?"
If they'd like it, offer **market research** (demand, seasonality, competing offers) using
the analytics and catalog data available, so any decision is informed. Report what the data
shows; do not translate it into a pricing recommendation.

**If the seller raises price themselves**, do not advise for or against it and do not
discuss trade-offs. If they name a **specific price**, go to Step 6 and draft exactly that.
If they ask whether they should change price, say pricing is their decision and this skill
doesn't advise on it, then return to the restock options above.

### Step 6 — Draft actions (DO NOT EXECUTE without approval)
Only if the seller has named a specific price, call `listings_patchListingsItem` with
**`mode: VALIDATION_PREVIEW`** so nothing changes yet. Show them, as a numbered list:
- exact SKU, current → the price **they specified**

Draft only. Add no commentary on whether the price is advisable, no projected effect, and
no revert date — if the seller wants a revert, they will say so.

Then **WAIT** for the seller to type "approve" (or adjust). Never re-run the patch
in live mode unless they explicitly approve.

### Step 7 — Summarize
Recap what was found, what (if anything) was drafted, and the single most important
next action. Keep it short and seller-friendly.

## Guardrails
- **Give no pricing guidance, in either direction.** Never suggest raising or lowering a
  price, never present a price change as an option, and never comment on whether a price the
  seller names is wise, safe, or advisable. Coming from Amazon, pricing advice carries
  implications this skill must not create. Lead with getting units in sooner. If the seller
  names a specific price, draft exactly that, mechanically, per
  [price-change-guardrails.md](references/price-change-guardrails.md); if they ask for advice,
  say pricing is their decision and this skill doesn't advise on it.
- Read-only by default. The only write tool is `listings_patchListingsItem`, and it
  is run in `VALIDATION_PREVIEW` until the seller approves.
- Never invent inventory or sales numbers — only report what the tools return.
- If a healthy SKU comes back, say so plainly; do not manufacture risk.

## References
- [reports-vs-ordermetrics.md](references/reports-vs-ordermetrics.md) — why we use
  `sales_getOrderMetrics` (sync) instead of the async Reports API.
- [price-change-guardrails.md](references/price-change-guardrails.md) — the preview +
  approval mechanics for a seller-specified price write. No pricing guidance.

From amzn/selling-partner-agentic-toolkit at bc33734, shown as plain text under its license: Apache-2.0 (permissive). The license text is in skills/stockout-prevention/SKILL.md.

• SKILL.md8.6 KB · eb583b963d71
• eval/
• evals.json4.6 KB · 889ca97da7bf
• references/
• price-change-guardrails.md1.9 KB · d5975fe4f1cb
• reports-vs-ordermetrics.md1.2 KB · f2ca4aca7a9d

4 files, 16 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.