> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.shipbob.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.shipbob.com/_mcp/server. # Inventory History This documentation provides an overview and API request examples for getting product inventory history events from ShipBob. ## Overview ShipBob’s Inventory History API can be used to fetch various inventory movements that occur within the ShipBob Network. An example of this is Warehouse Receiving Order (WRO) stow events as inventory is stowed at a fulfillment center. When stowing occurs, ShipBob’s On Hand quantity increases for that inventory item, and is considered ready to use for fulfillment. This API can be used to capture inventory events such as stow events, spot checks, restock events, and more. ## Request **Method**: POST **Authorization**: Bearer token, PAT generated from the ShipBob merchant dashboard. **Sandbox** * Base url: `https:/sandbox-api.shipbob.com/2026-01` * Endpoint: `/inventory/history:query` **Production** * Base url: `https://api.shipbob.com/2026-01` * Endpoint: `/inventory/history:query` ```json { "inventory_ids": [2543121], // optional "facility_id": 25, // required "event_category": "ReceivingStow", "start_date": "2025-06-18", // optional - last 90 days as default/max "end_date": null // optional } ``` ## Response **Response schema** ```json { "data": [ { "inventory_id": 2543121, "event_category": "ReceivingStow", "event_datetime": "2025-06-18T18:06:22.4716033", "shipbob_order_id": null, "merchant_user_id": 226071, "primary_reference": { "type": "WroAndBox", "value": "115316 7" }, "inventory_audit_event_id": 32204, "increment": { "facility_id": 25, "quantity_change": 1, "committed_quantity_change": 0, "lot_number": null, "expiration_date": null, "sku": "awe-jui", "location_id": 10010109, "yuki_id": "01JY23GXR7CSS4D25G5SC84VD1", "pack_description_id": "00000000000000000000000000", "operational_stage": null, "inventory_status": "" }, "decrement": { "facility_id": 25, "quantity_change": -1, "committed_quantity_change": 0, "lot_number": null, "expiration_date": null, "sku": "awe-jui", "location_id": 10010277, "yuki_id": "01JXFHF4PQVVDW8AYVHXAVC7RM", "pack_description_id": "00000000000000000000000000", "operational_stage": null, "inventory_status": "" }, "additional_reference": [] } ], "next": "https://api.shipbob.com/2026-01/inventory/history:query?cursor=23456" } ``` Each inventory event will include an **increment** and **decrement** object. The **increment** object is the event at the facility’s destination shelf, which updates the on-hand quantity for that item in ShipBob. The **decrement** object will decrease the specified quantity at the facility found within the object. Note that for some event categories (such as `InventoryAdjusted` spot-check events), the **decrement** may be `null` when the event only results in an increase. In addition, the event includes the **primary\_reference** property. Based on the Event Categories being queried, the **type** field will contain a definition for the corresponding **value** field. As an example, using the Event Category of `“ReceivingStow”` will return a **type** field of `“WroAndBox”`, and the **value** field will contain a combination of the WRO id and the box id. These two values will always be separated by a space. As another example, using the Event Category of `“OrderPicked”` will return a **type** field of `“OrderId”` and a **value** field that will contain the ShipBob order id, in case it needs to be fetched in any subsequent steps within the integration workflow. ### additional\_reference The **additional\_reference** array contains supplementary key-value pairs that provide context specific to the event category. For `InventoryAdjusted` events originating from a spot check, this array will include the bin number, spot check reason ID, and spot check reason name. **InventoryAdjusted example response** ```json { "data": [ { "inventory_id": 20191223, "event_category": "InventoryAdjusted", "event_datetime": "2026-03-03T20:04:58.5399235", "shipbob_order_id": null, "primary_reference": { "type": "SpotCheck", "value": "3558156" }, "inventory_audit_event_id": 414729326, "increment": { "facility_id": 193, "quantity_change": 1, "committed_quantity_change": 0, "lot_number": null, "expiration_date": null, "sku": "AWT0004-001-00M", "location_id": 19856450, "yuki_id": "01K7SE727PKYD7AP6STM85PQKT", "pack_description_id": "00000000000000000000000000", "operational_stage": { "id": 0, "description": "Ready" }, "inventory_status": "Available" }, "decrement": null, "additional_reference": [ { "key": "binNumber", "value": "P-01-A-230-A-029" }, { "key": "spotCheckReasonId", "value": "8" }, { "key": "spotCheckReasonName", "value": "Inventory Correction" } ] } ] } ``` For `InventoryAdjusted` spot check events, the `primary_reference.type` will be `"SpotCheck"` and the `primary_reference.value` will contain the spot check ID. The `additional_reference` array will contain the following keys: | Key | Description | | --------------------- | ----------------------------------------------------------- | | `binNumber` | The bin location where the spot check was performed. | | `spotCheckReasonId` | The numeric ID of the reason for the spot check adjustment. | | `spotCheckReasonName` | The human-readable name of the spot check reason. | The following spot check reason IDs and their corresponding names are supported: | spotCheckReasonId | spotCheckReasonName | | ----------------- | -------------------- | | 1 | FC Damage | | 2 | Receiving Error | | 3 | Disposal | | 4 | Churn Client | | 5 | Packaging | | 6 | Inventory Correction | | 7 | Hub Recieving Error | | 8 | Item ID Change | ## Supported Event Categories The following event categories can be sent via the POST request: | EventCategory | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `OrderPicked` | This will return any picking event that occurs during the outbound fulfillment process. | | `InventoryAdjusted` | Events that occur due to an inventory adjustment, including found inventory during spot-checks and setting on-hand quantities. | | `InventoryFacilityUpdated` | Events that occur when updating the facility of inventory locations. | | `AttributeUpdated` | Events that occur when updating inventory attributes. | | `InventoryReceived` | Events related to receiving new inventory, including returns. | | `InventoryRestocked` | Events related to restocking previously picked inventory. | | `ReceivingStow` | This will return stow events that occur from WROs which updates On Hand quantities. | | `KittingStow` | Events related to stowing inventory during the kitting process, including legacy kitting operations. | ## Pagination The response includes the field `inventory_audit_event_id` which can be used as a cursor. **Usage**: Begin with an empty cursor. To fetch additional records, use the last `inventory_audit_event_id` as a query parameter in subsequent requests. Example: **POST** `https://api.shipbob.com/2026-01/inventory/history:query?cursor=23456` This will return any records after (not including) the cursor value.