Skip to content

List stock levels

GET
/stores/{storeRef}/inventory/levels
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/inventory/levels?limit=20&offset=0&sort_by=product_name&sort_order=asc&filters=%5B%7B%22field%22%3A%22available%22%2C%22operator%22%3A%22lte%22%2C%22values%22%3A%5B%220%22%5D%7D%5D' \
--header 'x-api-key: <x-api-key>'

Returns a page of stock levels, one row per variant, with the quantity in each stock state. Use limit and offset to page, search to match product name or SKU and sort_by to order the rows. filters takes a JSON array of {field, operator, values} clauses, for example available at most 0 to find sold-out variants.

Required scopes: read:inventory

storeRef
required
string

The store’s ref, as returned by GET /stores.

limit
number
default: 20 >= 1 <= 100

Maximum number of rows to return, 1 to 100. Ignored by the export.

offset
number
0

Number of rows to skip. Ignored by the export.

search
string
<= 200 characters

Matches product name or SKU

sort_by
string
default: product_name
Allowed values: product_name sku available committed unavailable on_hand incoming

Field to sort by.

sort_order
string
default: asc
Allowed values: asc desc

Sort direction.

filters
string

Example

[{"field":"available","operator":"lte","values":["0"]}]

List-view filters: a JSON array of {field, operator, values}.

Media typeapplication/json
object
data
required
Array<object>
object
inventory_policy
required

What happens when stock runs out: deny stops sales, continue keeps selling.

string
Allowed values: deny continue
variant_id
required

Variant ID.

number
product_id
required

ID of the product the variant belongs to.

number
product_name
required

Product name.

string
product_image
required

Product image URL, or null.

string
nullable
variant_title
required

The variant’s option values joined with /, or null for a product without options.

string
nullable
sku
required

Stock keeping unit, or null.

string
nullable
location_id
required

ID of the location that holds the stock.

number
track_inventory
required

Whether stock is tracked for the variant.

boolean
available
required

Units that can be sold now.

number
committed
required

Units reserved by orders that are not yet fulfilled.

number
damaged
required

Units set aside as damaged.

number
quality_control
required

Units set aside for quality control.

number
safety_stock
required

Units held back as safety stock.

number
other
required

Units set aside for another reason.

number
unavailable
required

Total of damaged, quality control, safety stock and other.

number
on_hand
required

Units physically held: available, committed and unavailable together.

number
incoming
required

Units expected from open purchase orders.

number
updated_at
required

When the level last changed, as an ISO 8601 timestamp.

string
meta
required
object
total
required

Total number of items matching the request.

number
limit
required

Maximum number of items in this page.

number
offset
required

Number of items skipped before this page.

number
page
required

Current page number, starting at 1.

number
totalPages
required

Total number of pages.

number
hasNext
required

Whether a next page exists.

boolean
hasPrev
required

Whether a previous page exists.

boolean

Example

{
"data": [
{
"inventory_policy": "deny"
}
]
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}