📦 Inventory

This object represents the stock level for a single trackable unit.

This could be a base Product, a specific combination of variants defined by its unique SKU in Product.variant_combinations, or even a specific modifier.

It is expected to be updated frequently.

Fields

Name	Type	Description
`id`	string	Unique identifier for this inventory record (e.g., `inv_...`).
`product_id`	string	Link to the `Products` model (the merchant's offer).
`variant_combination_sku`	string	Optional. The final unique SKU from `Product.variant_combinations` that this inventory record applies to. If `null`, applies to the base product (if no variants) or a modifier.
`modifier_id`	string	Optional. Links to a specific `modifier` within `Product.modifier_groups`. Used to track availability of add-ons. If `null`, applies to base product or a variant combination.
`quantity`	integer	Nullable. The exact number of units available for this specific SKU or modifier. Can be `null` for non-quantity-tracked items.
`is_in_stock`	boolean	A simple, direct signal of availability (`true`/`false`) for this specific SKU or modifier. Crucial primary flag.
`updated_at`	string	Timestamp of the last modification (ISO 8601 UTC).

Sample JSON Examples

1. Simple Retail Product (In Stock)

This example shows the inventory record for a basic product (prod_tm_55667, Almarai Milk) which has no variants. variant_combination_sku is null. The quantity field shows 42 units are available, and is_in_stock is true.

{
  "id": "inv_tm_55667",
  "product_id": "prod_tm_55667",
  "variant_combination_sku": null,
  "modifier_id": null,
  "quantity": 42,
  "is_in_stock": true,
  "updated_at": "2025-10-16T11:20:05Z"
}

2. Retail Product Variant Combination (In Stock)

This example tracks inventory for a specific variant combination (prod_retail_tshirt, Small Red T-Shirt). The variant_combination_sku field links to the exact SKU (TSHIRT-S-RD) defined in the Product.variant_combinations. It shows 25 units are available (quantity: 25, is_in_stock: true).

{
  "id": "inv_TSHIRT-S-RD",
  "product_id": "prod_retail_tshirt",
  "variant_combination_sku": "TSHIRT-S-RD",
  "modifier_id": null,
  "quantity": 25,
  "is_in_stock": true,
  "updated_at": "2025-10-18T10:00:00Z"
}

3. Retail Product Variant Combination (Out of Stock)

This example tracks inventory for another variant combination (prod_retail_tshirt, Medium Blue T-Shirt). The variant_combination_sku links to its SKU (TSHIRT-M-BLU). It shows 0 units are available (quantity: 0) and is explicitly marked as unavailable (is_in_stock: false).

{
  "id": "inv_TSHIRT-M-BLU",
  "product_id": "prod_retail_tshirt",
  "variant_combination_sku": "TSHIRT-M-BLU",
  "modifier_id": null,
  "quantity": 0,
  "is_in_stock": false,
  "updated_at": "2025-10-18T10:05:00Z"
}

4. Restaurant Product Variant (Available)

This example tracks the availability of a specific restaurant product variant (prod_rbh_classic_burger, Single Patty, SKU RBH-CLASSIC-S). Since quantity isn't tracked precisely, it's null, but is_in_stock: true indicates it is currently available to order.

{
  "id": "inv_rbh_classic_burger_s",
  "product_id": "prod_rbh_classic_burger",
  "variant_combination_sku": "RBH-CLASSIC-S",
  "modifier_id": null,
  "quantity": null,
  "is_in_stock": true,
  "updated_at": "2025-10-15T22:15:00Z"
}

5. Restaurant Product Variant (Unavailable / Sold Out)

This example tracks the availability of another variant of the same restaurant product (prod_rbh_classic_burger, Double Patty, SKU RBH-CLASSIC-D). is_in_stock: false indicates that this specific variant is currently unavailable (e.g., ran out of patties needed for double).

{
  "id": "inv_rbh_classic_burger_d",
  "product_id": "prod_rbh_classic_burger",
  "variant_combination_sku": "RBH-CLASSIC-D",
  "modifier_id": null,
  "quantity": null,
  "is_in_stock": false,
  "updated_at": "2025-10-18T19:30:00Z"
}

6. Restaurant Modifier (Unavailable / Sold Out)

This example shows how to mark a specific modifier as unavailable. It targets the "Add Jalapeños" modifier (mod_jalapenos) for the burger product (prod_rbh_classic_burger). variant_combination_sku is null as it applies regardless of burger size. The crucial field is_in_stock: false signals that this specific add-on is currently unavailable.

{
  "id": "inv_rbh_mod_jalapenos",
  "product_id": "prod_rbh_classic_burger",
  "variant_combination_sku": null,
  "modifier_id": "mod_jalapenos",
  "quantity": null,
  "is_in_stock": false,
  "updated_at": "2025-10-17T14:10:00Z"
}

Fields#

Sample JSON Examples#

1. Simple Retail Product (In Stock)#

2. Retail Product Variant Combination (In Stock)#

3. Retail Product Variant Combination (Out of Stock)#

4. Restaurant Product Variant (Available)#

5. Restaurant Product Variant (Unavailable / Sold Out)#

6. Restaurant Modifier (Unavailable / Sold Out)#