Guide

Managing inventory

Use inventory data to prevent oversells, surface low stock, and keep menus accurate across channels.

Inventory endpoint Back to guides

Endpoints Inventory flow

List inventory GET /inventory Reserve inventory POST /orders Release inventory DELETE /orders/{order_id}

Signals

in_stock, low, out_of_stock

Refresh

Every shift

Overview

What this guide covers

Use GET /inventory to keep menus current. When you call POST /orders, the API reserves stock automatically. If an order is canceled with DELETE /orders/{order_id}, reserved inventory is released.

Inventory signals

Show badges when status is low.
Disable options when status is out_of_stock.
Surface alternatives before checkout to reduce errors.

Inventory flow

Fetch inventory when a store opens or before peak traffic.
Mark items as unavailable when status is out_of_stock.
Create orders and let the API reserve stock automatically.
Handle the out_of_stock error gracefully if stock changes mid-order.

Best practices

Refresh inventory for kiosks every 5 to 10 minutes.
Show suggested swaps when an item sells out.
Use a fallback message when inventory data is stale.

Example request and response

Requests

curl https://api.pbandj.io/v1/inventory \
  -H "X-API-Key: pbj_test_8dd1f2"

const response = await fetch('https://api.pbandj.io/v1/inventory', {
  headers: {
    'X-API-Key': 'pbj_test_8dd1f2',
  },
});

const data = await response.json();
console.log(data);

import requests

response = requests.get(
    "https://api.pbandj.io/v1/inventory",
    headers={"X-API-Key": "pbj_test_8dd1f2"},
)

print(response.json())

Responses

{
  "updated_at": "2026-03-15T10:12:00Z",
  "items": [
    {
      "type": "bread",
      "option": "sourdough",
      "available": 14,
      "reserved": 2,
      "status": "in_stock"
    },
    {
      "type": "peanut_butter",
      "option": "smooth",
      "available": 3,
      "reserved": 1,
      "status": "low"
    },
    {
      "type": "jelly",
      "option": "strawberry",
      "available": 0,
      "reserved": 1,
      "status": "out_of_stock"
    }
  ]
}

{
  "error": "unauthorized",
  "message": "The X-API-Key header is missing or invalid."
}