- Expected - Listed on open ASNs, RMAs and Other Deliveries that have not yet been received.
- Processed - Counted on an ASN, RMA or Other Delivery but not yet put-away.
- Put-Away - Has been received on an ASN, RMA or Other Delivery that has not yet been committed to the inventory. If you have auto-commit enabled this should always be 0.
- Available - Available for new orders. Backordered amounts are not reflected as a negative Available amount but are tracked separately as “Backordered”.
- Allocated - Allocated to existing orders but not yet Reserved.
- Reserved - Reserved to a specific shelf location and waiting to be picked.
- Picked - Picked from the shelves but not yet shipped.
- Backordered - Reserved by existing orders but not in stock. Will be automatically converted to Reserved when stock is added. Backordered quantities are not reflected in the Available amount as a negative number.
- Advertised - The “Available” quantity plus the virtual BOM quantity. The virtual BOM quantity is controlled by a product’s “Virtual Inventory” attribute.
- Held - On hand but placed on hold (quarantined, damaged, expired, recalled, etc.). Held inventory remains counted in the on-hand total but is excluded from the Available quantity and cannot be allocated, picked, or packed until the hold is released. See inventory.holdReasons for the reasons visible to a merchant and inventory.holdSearch to list individual holds.
- Status - Enabled/Disabled - If “Disabled”, the product is effectively deleted and will not appear in responses to inventory requests.
- Visibility - Visible/Not Visible - If “Not Visible”, the product will not appear in the inventory list but may still be ordered via the Merchant Panel.
Methods
- inventory.list
- inventory.lots
- inventory.detailed
- inventory.detailed_packaging
- inventory.holdSearch
- inventory.holdReasons
Entity Properties
inventory.list
inventory.list (string|array|null $skus, int|null $warehouseId, string|null $updatedSince, bool $withHeldBreakdown = false)
Get inventory levels for one or more products by SKU. If a warehouse is not specified the sum of all warehouse inventories will be returned, otherwise the inventory levels for the specified warehouse will be returned.
Each item includes a qty_held quantity. When withHeldBreakdown is true, each item also includes a qty_held_by_reason object that breaks the held quantity down by hold reason.
Parameters
string | array | null
SKUs. If not specified then inventory for all SKUs will be returned.
string- Get inventory for a single product by SKU.array- Get inventory for the specified products by SKU.null- Get inventory for all products.
integer | null
Warehouse. If not specified, returned values represent sums of all warehouses.
string | null
Return only SKUs updated since the time specified in the format
2008-07-01T22:38:07+00:00.boolean
default:"false"
When
true, each item is augmented with a qty_held_by_reason object keyed by parent (system) hold reason code. Defaults to false, which preserves the legacy response shape and avoids the additional per-call rollup query.Return Value
An array of Inventory Items or an empty array if there were no matching SKUs.Example Request
Get inventory for two SKUs:Request
Request
Request
Example Response
Response
inventory.lots
inventory.lots (null|object $filters, array $options = [])
Retrieve list of lots by filters.
Parameters
null | object
Filters to apply for the search.
null- Retrieve list of all Lots.object- Retrieve list of Lots using specified “Search Filters”.
null | object
Options to apply for the search.
null- No options will be applied.object- Apply specified “Search Options”.
Return Value
An array of objects. Each object will contain Lot Properties.Example Request
Example Response
Error Codes
inventory.detailed
inventory.detailed (string|array|null $skus, string|null $updatedSince, bool $withHeldBreakdown = false)
Get global and per-warehouse inventory levels for one or more products by SKU.
Each item — and each per-warehouse detailed entry — includes a qty_held quantity. When withHeldBreakdown is true, each item is additionally augmented with a qty_held_by_reason object (held quantity grouped by parent hold reason code) and, when user-defined sub-reasons exist, a qty_held_by_user_reason object that breaks each parent reason down by its user-defined child reasons. Both rollups are reported at the item level only, not per warehouse.
Parameters
string | array | null
SKUs. If not specified then inventory for all SKUs will be returned.
string- Get inventory for a single product by SKU.array- Get inventory for the specified products by SKU.null- Get inventory for all products.
string | null
Return only SKUs updated since the time specified in the format
2008-07-01T22:38:07+00:00.boolean
default:"false"
When
true, each item is augmented with a qty_held_by_reason object and, where applicable, a qty_held_by_user_reason object. Defaults to false, which preserves the legacy response shape and avoids the additional hold rollup queries.Return Value
An array of detailed items inventory, or an empty array if there were no matching SKUs.Example Request
Example Response
The example below was requested withwithHeldBreakdown set to true, so each item includes the qty_held_by_reason (and, where user-defined sub-reasons exist, qty_held_by_user_reason) rollups. With the default false, those two fields are omitted but qty_held is still present on every item and warehouse entry.
Error Codes
inventory.detailed_packaging
inventory.detailed_packaging (string|array|null $skus, string|null $updatedSince, bool $withHeldBreakdown = false)
Get global and per-warehouse inventory levels for Packaging Features by SKU. This method is similar to inventory.detailed but returns only Packaging Feature types (Container, Supplies, and Infill) that can have inventory. Regular products and other Packaging Feature types are excluded from the results.
As with inventory.detailed, each item and warehouse entry includes a qty_held quantity, and the optional withHeldBreakdown parameter adds the item-level qty_held_by_reason (and qty_held_by_user_reason) rollups.
Parameters
string | array | null
SKUs. If not specified then inventory for all Packaging Feature SKUs will be returned.
string- Get inventory for a single Packaging Feature by SKU.array- Get inventory for the specified Packaging Features by SKU.null- Get inventory for all Packaging Features (Container, Supplies, and Infill).
string | null
Return only SKUs updated since the time specified in the format
2008-07-01T22:38:07+00:00.boolean
default:"false"
When
true, each item is augmented with a qty_held_by_reason object and, where applicable, a qty_held_by_user_reason object. Defaults to false.Return Value
An array of detailed Packaging Feature inventory, or an empty array if there were no matching SKUs. Only Packaging Feature types (Container, Supplies, and Infill) are included in the response.Example Request
Example Response
Error Codes
inventory.holdSearch
inventory.holdSearch (null|object $filters, array $options = [])
Search the merchant’s active and released inventory holds. Results are always scoped to the calling merchant’s own inventory — no filter combination can return another merchant’s holds. The response is paginated and shaped like inventory.lots: { results, totalCount, numPages }. Each result row includes structured lot and reason objects alongside the core hold fields.
For privacy, hold rows do not expose internal location identifiers or labels — including inside nested objects. The embedded lot object contains no location information. Identify the held inventory using sku, lot.lot_number, and reason.code instead.
Parameters
null | object
Filters to apply to the search. Every key is optional, and unknown keys are rejected. Combine any of:
product_id(integer) — holds on a specific product.sku(string) — holds on a specific SKU.warehouse_id(integer) — restrict to one warehouse. Must be a warehouse the merchant can access.reason_code(string) — exact hold reason code. Matches that reason only; it does not roll child reasons up to their parent.lot_id(integer) — holds on a specific lot by internal lot ID.lot_number(string) — holds on a specific lot by lot number.status(string) —active(not yet released) orreleased.held_after(string) — only holds placed on or after this ISO 8601 timestamp.held_before(string) — only holds placed on or before this ISO 8601 timestamp.
lot filter is not supported — use lot_id or lot_number.null | object
Pagination and sorting:
sort_field(string) —held_at(default),released_at, orhold_id.sort_dir(string) —ascordesc(defaultdesc).page(integer) — 1-based page number (default1).limit(integer) — page size, capped at100(default50).
Return Value
An object withresults (an array of Inventory Hold objects), totalCount, and numPages.
Example Request
Active damage holds for one SKU, newest first:Request
Example Response
Response
Error Codes
inventory.holdReasons
inventory.holdReasons()
Retrieve the list of active inventory hold reasons that are visible to the calling merchant.
Parameters
This method takes no parameters.Return Value
An array of objects, each containing the Hold Reason Properties.Example Request
Request
Example Response
Response
Entity Properties
Inventory Item
string
A unique identifier for a product. The SKU does appear on the packing slip. It is recommended that this be human-readable and end with a per-pack quantity to facilitate proper receiving. For example, a single blue widget may be “BlueWidget-1” and a pack of 5 blue widgets may be “BlueWidget-5”. Maximum character length is 64.
integer
The “Expected” quantity.
integer
The “Processed” quantity.
integer
The “Put-Away” quantity.
integer
The “Available” quantity.
integer
The “Allocated” quantity.
integer
The “Reserved” quantity.
integer
The “Picked” quantity.
integer
The “Held” quantity — inventory placed on hold (quarantined, damaged, expired, recalled, etc.). Held inventory stays counted in
qty_on_hand but is excluded from qty_available and cannot be allocated, picked, or packed until the hold is released.integer
The “Backordered” quantity. This quantity will not be present for single-warehouse requests since backordered amounts are not apportioned to specific warehouses.
integer
The “Advertised” quantity. This is the “Available” quantity plus the virtual BOM quantity. The virtual BOM quantity is controlled by a product’s “Virtual Inventory” attribute.
integer
The Quantity On Hand is
qty_processed + qty_putaway + qty_available + qty_allocated + qty_reserved + qty_picked + qty_heldobject
Present only when a request is made with
withHeldBreakdown set to true. An object that breaks qty_held down by parent (system) hold reason code, e.g. { "damaged": "2.0000", "qc_inspection": "1.0000" }. Reasons with no held quantity are omitted; an empty object means nothing is held.object
Present only on
inventory.detailed / inventory.detailed_packaging requests made with withHeldBreakdown set to true, and only when user-defined sub-reasons are in use. A nested object keyed by parent reason code, each mapping to its user-defined child reason codes and their held quantities, e.g. { "qc_inspection": { "qc_lab_review": "1.0000" } }.Lot Properties
integer
The internal lot ID.
integer
Flag whether lot is active.
string
The “SKU” property.
string
The “Name” property.
string
The “Lot Number” property.
string
The “Expiration Date” property.
string
The “Origination Date” property.
string
The “Group Value” property.
string
The “Created At” property in ISO 8601 format.
array
A list of locations.
string
The “Put-Away” quantity.
string
The “Available” quantity.
string
The “Reserved” quantity.
string
The quantity of the lot currently on hold across all of its locations.
boolean
true when the lot has at least one active (unreleased) hold, otherwise false.Inventory Hold Properties
Returned by inventory.holdSearch. For privacy, hold rows do not include any location identifier or label — including inside nested objects.integer
The internal hold ID.
string | null
The SKU of the held product, or
null if it cannot be resolved.string | null
The name of the held product, or
null if it cannot be resolved.string | null
Deprecated — use
lot.lot_number instead. The lot number of the held inventory, or null when the hold is not lot-specific.string | null
Deprecated — use
reason.code instead. The hold reason code for this hold.string | null
Deprecated — use
reason.label instead. The human-readable hold reason label as configured in the merchant’s account.object | null
A subset of Lot Properties for the held lot, or
null when the hold is not lot-specific or the lot entity no longer exists. Contains no location information, quantity rollups, or product fields. Fields:lot_id(integer) — the internal lot ID.lot_number(string | null) — the lot number.expiration_date(string | null) — the expiration date.origination_date(string | null) — the origination date.group_value(string | null) — the group value.is_active(integer) — flag whether the lot is active.is_expired(integer) — flag whether the lot is expired (snapshot value, as last computed).created_at(string | null) — when the lot was created.
object | null
A Hold Reason object for this hold, or
null when no reason is associated. Fields: code, label, display_group.string
The quantity placed on hold by this hold record.
string
When the hold was placed, in ISO 8601 format.
string | null
When the hold was released, in ISO 8601 format, or
null if the hold is still active.string | null
Free-text notes recorded when the hold was placed, or
null.string
active when released_at is null, otherwise released.Hold Reason Properties
string
The stable machine-readable identifier for the reason. Use this value when calling other endpoints that accept a
reason_code.string
The human-readable label for the reason as configured in the merchant’s account.
string
The bucket the reason is grouped under in the UI. Built-in groups are
Hold, Review, Expired, and Unsellable; user-defined reasons may use any text up to 25 characters.