Catch display-vs-actual-stock mismatches

Why this matters

Showing “in stock” on a sold-out item is one of the most expensive bugs in ecommerce. The customer:

1. Adds it to cart
2. Pays
3. Gets a delayed-fulfillment email
4. Refunds + chargebacks + a one-star review

You eat the payment processing fee, the support time, the customer acquisition cost, and the SEO damage from a public review that calls you a scam.

The root cause is almost always inventory desync — your warehouse system says 0, your storefront cache says 4. Catching this in code (a InventoryMismatchError thrown when checkout discovers the gap) is easy. Catching it in operations means surfacing the error in 5 minutes, not 5 hours.

Agentry buckets inventory errors by warehouse and SKU automatically — you can see which warehouse’s sync job is misfiring, against which products, trending which direction.

What you get

• Per-warehouse error rate for the inventory sync pipeline
• Top SKUs implicated (so you can pull them from the storefront proactively)
• A trend line — is it spiking right now, or is this a chronic 2% noise floor?

Walk through it

agentry_list_cases {
  project_id: "default",
  status: "open",
  matching: "Inventory|StockMismatch|OutOfStock",
  window_hours: 24
}

{
  "cases": [
    {
      "case_id": "c_inv_1",
      "fingerprint": "f_inv_a",
      "error_type": "InventoryMismatchError",
      "message": "Expected stock=4 actual=0 sku=wireless-buds-v2 warehouse=us-west",
      "events_count": 142,
      "users_affected": 38,
      "first_seen_at": "2026-05-15T09:22:00Z"
    },
    {
      "case_id": "c_inv_2",
      "fingerprint": "f_inv_b",
      "error_type": "OutOfStockError",
      "message": "Concurrent checkout drained inventory sku=blender-mini warehouse=us-west",
      "events_count": 68,
      "users_affected": 21,
      "first_seen_at": "2026-05-15T14:05:00Z"
    }
  ]
}

agentry_analytics_query {
  project_id: "default",
  query: "
    select
      toStartOfHour(timestamp) as hour,
      properties.warehouse_id as warehouse,
      count() as errors
    from events
    where event = '$exception'
      and (properties.$exception_type = 'InventoryMismatchError'
           or properties.$exception_type = 'OutOfStockError')
      and timestamp > now() - interval 7 day
    group by hour, warehouse
    order by hour desc
    limit 50
  "
}

{
  "rows": [
    { "hour": "2026-05-16T13:00:00Z", "warehouse": "us-west", "errors": 38 },
    { "hour": "2026-05-16T12:00:00Z", "warehouse": "us-west", "errors": 41 },
    { "hour": "2026-05-16T11:00:00Z", "warehouse": "us-west", "errors": 27 },
    { "hour": "2026-05-16T10:00:00Z", "warehouse": "us-west", "errors":  8 },
    { "hour": "2026-05-16T13:00:00Z", "warehouse": "us-east", "errors":  2 },
    { "hour": "2026-05-15T18:00:00Z", "warehouse": "us-west", "errors":  4 }
  ]
}

The output

Inventory sync errors (24h)

Warehouse    Events    Trend      Top SKUs
─────────────────────────────────────────────────────────────
us-west        210     SPIKING ★  wireless-buds-v2 (142), blender-mini (68)
us-east          5     normal     -
eu-west          1     normal     -

us-west hourly:
  10:00   8  ─
  11:00  27  ▌
  12:00  41  █     ★ sync job stuck
  13:00  38  ▊

Cases open:
  c_inv_1  InventoryMismatchError       142 events, 38 users
  c_inv_2  OutOfStockError (concurrent)  68 events, 21 users

Recommended actions (in order):
  1. Force full-sync us-west warehouse
  2. Pull wireless-buds-v2 + blender-mini from hero
  3. Manually refund affected orders, draft apology
  4. (Once stable) Add an alert: us-west errors > 20/hour

Setting it up

Send errors with warehouse_id and sku as properties so the agent can group:

try {
  await reserveInventory(sku, qty, warehouseId);
} catch (err) {
  await fetch(`https://api.agentry.sh/v1/logs/${PROJECT_ID}/`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.AGENTRY_DSN}`,
      "Content-Type": "application/json",
      "User-Agent": "fulfillment/1.0",  // REQUIRED — Cloudflare 403s default UAs
    },
    body: JSON.stringify({
      message: err.message,
      stack: err.stack,
      error_type: err.constructor.name,  // 'InventoryMismatchError' etc.
      properties: {
        warehouse_id: warehouseId,
        sku,
        expected: err.expected,
        actual: err.actual,
      },
    }),
  });
  throw err;
}

Once errors flow with warehouse_id, you can also register a webhook that pings #ops every time us-west exceeds 20/hour — see staging-watcher for the Routine pattern.

Variations

• “Same query but split by sync-job version — did the deploy at 09:30 introduce the bug?”
• “Per-warehouse: time between ‘last successful sync’ and ‘first mismatch’. Are the warehouses with longer sync gaps the noisy ones?”
• “Build a Routine that pulls SKUs out of the homepage hero automatically when their mismatch rate exceeds 10%.”
• “Show me which customers were affected by today’s us-west spike — I want to send personal apology refunds.”