Get variant balance
Gets on-hand, reserved, and available inventory for a Variant, in total and per warehouse.
available is publishable quantity. The response has the Variant totals (onHand, reserved, available) and the warehouses list, with one line per warehouse. The totals are always the sum of the lines.
curl "$BACKEND_URL/v1/variants/$VARIANT_ID/inventory" \
-H "Authorization: Bearer mk_your_api_key"Example: 6 units in the default warehouse and 4 in the branch give onHand: 10 in total.
The warehouses list
- It has every active warehouse of the seller, including the ones where the Variant never had a movement (all zero). An archived warehouse does not show up.
- The default warehouse comes first. The others follow by
name. - For the balance of one warehouse, look for its
warehouseIdin the list.
Derived kits
For derived kits, available is calculated at read time, warehouse by warehouse: in each one, it is the smallest whole-unit ratio of the active components that are there. The totals sum the warehouses, and the kit's reserved is always 0. Parts in different warehouses do not make a kit.
api_keyAuthorizationBearer <token>API key (mk_...)
variantId*string^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidCurrent on-hand, reserved and available inventory: the totals of the variant and the split by warehouse.
application/json- response
Current inventory balance of one variant: the total, and its split by warehouse.
variantId*stringVariant whose stock this is.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidonHand*integerPhysical or owned units on hand, summed over every warehouse in warehouses.
-9007199254740991 <= value <= 9007199254740991reserved*integerUnits reserved for open commitments, summed over every warehouse in warehouses.
0 <= value <= 9007199254740991available*integerPublishable units: onHand minus reserved, summed over every warehouse in warehouses.
-9007199254740991 <= value <= 9007199254740991updatedAt*stringWhen this balance last changed, in any warehouse.
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timewarehouses*array<>The balance in each active warehouse of the seller, including the ones where this variant has no stock yet (zeros). The default warehouse comes first, then the others by name. The totals above are the sum of these lines.
curl -X GET "https://example.com/v1/variants/497f6eca-6276-4993-bfeb-53cbbbba6f08/inventory"{ "variantId": "47c9f819-fcf6-4478-b21a-678ecc594a11", "onHand": 10, "reserved": 2, "available": 8, "updatedAt": "2026-10-10T12:00:00.000Z", "warehouses": [ { "warehouseId": "b7e2a1c4-5d3f-4e8a-9b6c-2f1d0a8e7c35", "onHand": 7, "reserved": 0, "available": 7, "updatedAt": "2026-10-10T12:00:00.000Z" }, { "warehouseId": "e41c9a07-26b8-4d53-a0f1-8c3b7d5e9a12", "onHand": 3, "reserved": 2, "available": 1, "updatedAt": "2026-10-09T08:00:00.000Z" } ]}