Inventories

Inventories keep track of the stock of SKUs and options at a specific location.

An inventory consists of multiple inventory entries. An inventory entry represents the stock of a specific SKU or option.

Inventories are empty by default. SKUs or options not specified in the inventory are considered to have an unlimited supply.

Inventories cannot be created or deleted. They are inherently associated with each location.

Inventory Endpoint Scopes

Each inventory endpoint exists in two flavours:

• An unscoped endpoint, to retrieve or update the inventory of a specific location independently of any catalogs. E.g., GET /location/inventory.
• A catalog-scoped endpoint that filters retrievals and restricts updates to items belonging to a catalog. E.g., GET /catalogs/:id/location/inventory.

Catalog-scoped endpoints are historical and can still be useful. For example, you can use the catalog-scoped update endpoint immediately after a catalog upload to ensure that the update only affects items in that catalog.

The main drawback of catalog-scoped update endpoints is that they require the catalog to be up to date on HubRise, which is often impractical: while inventories are generally updated in real time, catalog updates are usually triggered on user request, at a lower frequency.

For this reason, we recommend using the unscoped endpoints for new integrations, and upgrading existing integrations to them.

The unscoped endpoints require an inventory.write or inventory.read scope, while the catalog-scoped endpoints can also be used with a catalog.write or catalog.read scope for historical reasons.

Retrieve Inventory

Unscoped endpoint

Returns the inventory of SKUs and options at the specified location.

Example request:

GET /location/inventory

[  {    "sku_ref": "COKE",    "stock": "3",    "expires_at": null  },  {    "sku_ref": "PEPSI",    "stock": "0",    "expires_at": "2020-08-05T08:00:00+02:00"  },  {    "option_ref": "EGG",    "stock": "1",    "expires_at": null  }]

In the above example:

• The sku with the ref COKE has 3 items available.
• The sku with the ref PEPSI is out of stock and will be available again at the specified date.
• The option with the ref EGG has 1 item available.

Catalog-scoped endpoint

Only SKUs and options belonging to the catalog designated in the endpoint are returned.

Example request:

GET /catalogs/87yu4/location/inventory

[  {    "sku_ref": "COKE",    "stock": "3",    "expires_at": null  }]

Update Inventory

Unscoped endpoint

Overwrites the inventory of SKUs and options at the specified location.

This operation resets all inventory entries that are not included in the request.

The request body has the same format as the Retrieve Inventory response. Each entry in the request should include:

• A sku_ref or an option_ref key.
• A stock key indicating quantity. The value should be a non-negative decimal, with up to 3 decimal places. A value of 0 means out of stock. Entries with a value of null are ignored.
• An optional expires_at key, only allowed if stock is 0, indicating the date at which the item will be available again.

Example request:

PUT /location/inventory

[  {    "sku_ref": "COKE",    "stock": "5"  },  {    "option_ref": "EGG",    "stock": "0",    "expires_at": "2020-08-05T08:00:00+02:00"  }]

Clients listening to the inventory.patch callback receive a notification each time an entry expires. If multiple entries expire at the same time, a single notification is sent with all the expired entries.

Catalog-scoped endpoint

Overwrites the inventory at the specified location, but only for SKUs and options belonging to the catalog designated in the endpoint.

This operation resets inventory entries for SKUs and options that belong to the catalog but are not included in the request. Inventory entries that do not belong to the catalog remain unchanged.

Example request:

PUT /catalogs/87yu4/location/inventory

[  {    "sku_ref": "COKE",    "stock": "5"  }]

Patch Inventory

Unscoped endpoint

Updates a selected set of entries, while leaving the other entries unchanged.

The request body has the same format as Update Inventory. A stock value of null means that the entry should be removed from the inventory, signifying that the stock is unlimited.

The response contains only the modified entries for brevity and utility.

Example request:

Given the existing inventory:

[  {    "sku_ref": "COKE",    "stock": "3",    "expires_at": null  },  {    "option_ref": "EGG",    "stock": "1",    "expires_at": null  }]

When applying this operation:

PATCH /location/inventory

[  {    "sku_ref": "COKE",    "stock": null  },  {    "sku_ref": "PEPSI",    "stock": "2"  }]

The updated inventory becomes:

[  {    "sku_ref": "PEPSI",    "stock": "2",    "expires_at": null  },  {    "option_ref": "EGG",    "stock": "1",    "expires_at": null  }]

Catalog-scoped endpoint

Updates a selected set of entries, but only for SKUs and options belonging to the catalog designated in the endpoint.

Example request:

PATCH /catalogs/87yu4/location/inventory

[  {    "sku_ref": "COKE",    "stock": null  }]