Inventory Webhook Reference

Payload Field Reference

Both Inventory Change and Available Stock Change webhooks share the same payload structure. Each field represents a different view of a SKU's stock at a pickup warehouse.

Field	Description
`stock_quantity`	Physical on-hand quantity — units that have been put away into stock locations and are part of warehouse inventory.
`incoming_quantity`	Units that have arrived at the warehouse but not yet been put away (e.g. waiting at the receiving dock). Not yet counted in `stock_quantity`.
`reserved_quantity`	Units of `stock_quantity` that are manually reserved (typically via the Reserved Stock API). Not tied to any specific in-process order.
`awaiting_quantity`	Units that are waiting to be packed, or currently being packed but not yet completed. Decreases only when the order moves to Ready-to-Ship status.
`available_quantity`	available_quantity = stock_quantity − reserved_quantity − awaiting_quantity
`adjust`	Delta of the current event. Positive = quantity added, negative = quantity removed.
`refer_type`	Type of business document that caused the change. See scenario tables below.
`refer_code`	Identifier of the business document (ASN code, order code, adjustment code, etc.).
`note`	Free-text description of the event.
`update_time`	Unix timestamp (seconds) when the change occurred.
`condition_level`	Stock condition grade (`A`,`D1`,`D2`,`D3` = good, etc.). Each condition level is tracked separately.

1. Inventory Change

Tracks: Physical on-hand quantity (stock_quantity)

Fires whenever the physical stock count of a SKU at a pickup warehouse changes — i.e. units are physically added to or removed from the warehouse.

Trigger Scenarios

#	Scenario	`adjust`	`refer_type`	`refer_code`
1	Inbound putaway completed — ASN goods received into stock	`+qty`	`inbound`	ASN code (e.g. `SM-VN-…`)
2	Outbound handover completed — order picked, packed and shipped	`−qty`	`outbound`	Order code
3	Return putaway completed — RTO / customer return received back into stock	`+qty`	`return`	Return order code
4	Abnormal inventory adjustment — damaged, lost, found, cycle-count correction	`+/−qty`	`abnormal`	Adjustment code

Abnormal events: An abnormal adjustment fires three webhooks simultaneously — Inventory Change, Available Stock Change, and Abnormal Inventory Change Push (which carries the reason/category). Subscribe to whichever fits your downstream system.

Use this webhook to keep your ERP / accounting / WMS physical inventory snapshot in sync with Boxme warehouse. This is the source of truth for what is physically in the warehouse right now.

2. Available Stock Change

Tracks: Sellable quantity (available_quantity)

Fires whenever the sellable (available-to-promise) quantity of a SKU changes — i.e. the quantity that can still be promised to a new buyer.

Formula:

available_quantity = stock_quantity − reserved_quantity − awaiting_quantity

The hook fires whenever any of the three terms on the right changes.

Trigger Scenarios

#	Scenario	`adjust`	`refer_type`	Physical stock changed?
1	Order received — units held in `awaiting_quantity` to be packed	`−qty`	`hold`	No
2	Inbound putaway completed — new stock arrives	`+qty`	`inbound`	Yes
3	Return putaway completed — returned units back into available pool	`+qty`	`return`	Yes
4	Order Ready-to-Ship & handed over — `awaiting_quantity −1` and `stock_quantity −1` cancel each other; `available_quantity` is unchanged	`0`	`release`	Already accounted for
5	Order cancelled before pick & pack — `awaiting_quantity` released back to available	`+qty`	`void`	No
6	Abnormal inventory change — damaged, found, cycle-count adjustment	`+/−qty`	`abnormal`	Yes

Abnormal events: The system fires all three webhooks together: Inventory Change, Available Stock Change, and Abnormal Inventory Change Push.

Use this webhook to update listing availability on marketplaces, OMS, or storefront in real time. This is the source of truth for what can still be sold.

Choosing the Right Webhook

The two webhooks are complementary, not duplicates.

Need	Subscribe to
Keep physical warehouse stock in sync with ERP / accounting	Inventory Change
Keep sellable quantity in sync with sales channels	Available Stock Change
Both physical and sellable views	Both (each fires independently per business event)

Example: Full Order Lifecycle

Normal flow (order placed → shipped)

T0 — Buyer places order

awaiting_quantity +1 → available quantity drops.

Available Stock Change   adjust = -1   refer_type = hold

Inventory Change is NOT fired — no physical movement yet.

T1 — Warehouse picks & packs, order moves to Ready-to-Ship

stock_quantity −1 and awaiting_quantity −1 cancel each other in the available formula.

Inventory Change         adjust = -1   refer_type = outbound
Available Stock Change   adjust =  0   refer_type = release

Cancellation before pick & pack

awaiting_quantity released; physical stock never moved.

Available Stock Change   adjust = +1   refer_type = void

Inventory Change is NOT fired.

Stock Unit Lifecycle

Note: The Awaiting state represents units in awaiting_quantity — waiting to be packed or currently being packed. This is distinct from reserved_quantity, which tracks manually held units not tied to any specific in-process order.

Inventory Webhook Reference

Payload Field Reference#

1. Inventory Change#

Trigger Scenarios#

When to Subscribe#

2. Available Stock Change#

Trigger Scenarios#

When to Subscribe#

Choosing the Right Webhook#

Example: Full Order Lifecycle#

Normal flow (order placed → shipped)#

Cancellation before pick & pack#

Stock Unit Lifecycle#

Payload Field Reference

1. Inventory Change

Trigger Scenarios

When to Subscribe

2. Available Stock Change

Trigger Scenarios

When to Subscribe

Choosing the Right Webhook

Example: Full Order Lifecycle

Normal flow (order placed → shipped)

Cancellation before pick & pack

Stock Unit Lifecycle