Inventory data integration

Stock is managed by the combination of product × warehouse. A single product can hold stock in multiple warehouses, each with its own independent quantity. Stock changes are recorded in full as stock movement history (stock_movement).

Main fields (inventory)

Related scopes

• inventory.read — read stock counts
• inventory.write — update stock counts (record stock movements)
• warehouse.read / warehouse.write — operate the warehouse master

Main endpoints

GET   /v1/inventory                  ← list stock
GET   /v1/inventory/{product_id}     ← a product's stock by warehouse
PATCH /v1/inventory/{product_id}     ← update stock count (delta or absolute value)
POST  /v1/stock_movements            ← record a stock movement
GET   /v1/stock_movements            ← stock movement history
GET   /v1/warehouses                 ← list warehouses

Update method (delta vs. absolute value)

// Overwrite with an absolute value (at stocktake)
PATCH /v1/inventory/prd_a01
{ "warehouse_id": "wh_main", "quantity": 42 }

// Increment/decrement with a delta (for stock movements, recommended)
POST /v1/stock_movements
{
  "product_id": "prd_a01",
  "warehouse_id": "wh_main",
  "delta": -3,
  "reason": "sale",
  "reference_id": "rcp_xyz789"
}

Specifying a delta is recommended, because it is less prone to conflicts on concurrent updates and leaves a history.

Webhook events

• inventory.changed — stock count changed
• inventory.low_stock — fell below the threshold
• inventory.out_of_stock — out of stock
• stock_movement.created — stock movement recorded

WMS integration patterns

WMS-driven (recommended)

• The WMS is the source of truth for stock
• Sync by POSTing stock_movement to ReceiptRoller
• Configure ReceiptRoller not to auto-decrement stock when it issues a receipt

ReceiptRoller-driven

• ReceiptRoller is the source of truth for stock (for small stores)
• Auto-decremented on receipt issuance via POS integration
• The WMS follows via the inventory.changed Webhook

How to use reserved

When you need to place a hold for e-commerce orders — "added to cart", "before payment", etc. — increase reserved in advance. On payment completion, decrement from quantity; on cancellation, return reserved.

Related guides

• Product master (PIM)
• Webhook overview
• Back to the developer help index