> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/stock_items.md).
# Stock items
The stock item object and the allowed CRUD operations on the related resource endpoint
A stock item keeps the inventory of an [SKU](/core-api-reference/skus.md) in a given [stock location](/core-api-reference/stock_locations.md).
{% hint style="info" %}
The actual availability of an item may vary depending on active [stock reservations](/core-api-reference/stock_reservations.md). If active stock reservations are associated with a stock item, the *available* quantity equals the stock item quantity minus the [reserved stock](/core-api-reference/reserved_stocks.md) quantity.
{% endhint %}
When you place an [order](/core-api-reference/orders.md) the related stock is reserved. As soon as the order is approved the related stock is released and the stock item quantities get decremented. When a [return](/core-api-reference/returns.md) is approved and the associated items are restocked, the stock item quantities get incremented.
{% hint style="warning" %}
When updating stock items quantities via [imports](/core/importing-resources.md), existing records may be updated inconsistently: this occurs when the quantity of a stock item is less than the existing reserved stock, which is probably an overselling symptom. To avoid this scenario, we recommend passing the `_validate` trigger attribute for each of the imported inputs, as shown in [this example](/core/importing-resources.md#importing-a-list-of-stock-items-csv).
{% endhint %}
## Tracking low stock
You can set a `low_quantity` threshold on a stock item to define the quantity level below which it is considered low on stock. Once that threshold is set, you can use the `low_stock` filter scope to retrieve all the stock items whose `quantity` has dropped below their own `low_quantity`, which is useful for building low-stock alerts and replenishment workflows.
{% hint style="warning" %}
Stock items with no `low_quantity` set are never returned by this scope, so they won't show up in a `low_stock` alert even if their `quantity` reaches zero.
{% endhint %}
{% tabs %}
{% tab title="Request" %}
The following request fetches all the stock items that are currently low on stock:
```shell
curl -g -X GET \
'https://yourdomain.commercelayer.io/api/stock_items?filter[q][low_stock]=true' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the paginated collection of stock items whose `quantity` is lower than their `low_quantity`:
{
"data": [
{
"id": "XAyRWNUzyN",
"type": "stock_items",
"links": {
"self": "https://yourdomain.commercelayer.io/api/stock_items/XAyRWNUzyN"
},
"attributes": {
"sku_code": "TSHIRTMM000000FFFFFFXLXX",
"quantity": 5,
"low_quantity": 10,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": "ANY-EXTERNAL-REFEFERNCE",
"reference_origin": "ANY-EXTERNAL-REFEFERNCE-ORIGIN",
"metadata": {
"foo": "bar"
}
},
"relationships": {
"stock_location": {
"links": {
"self": "https://yourdomain.commercelayer.io/api/stock_items/XAyRWNUzyN/relationships/stock_location",
"related": "https://yourdomain.commercelayer.io/api/stock_items/XAyRWNUzyN/stock_location"
}
},
"sku": {
"links": {
"self": "https://yourdomain.commercelayer.io/api/stock_items/XAyRWNUzyN/relationships/sku",
"related": "https://yourdomain.commercelayer.io/api/stock_items/XAyRWNUzyN/sku"
}
}
},
"meta": {
"mode": "test",
"organization_id": "xRRkjDFafe",
"trace_id": "69abaa3545913c78132e5578bd26208d44aa9043647d78698fd0021f3958cd74"
}
},
{
"other": "... any other stock item currently low on stock"
}
],
"meta": {
"record_count": 3,
"page_count": 1,
"page_size": 10,
"page_number": 1,
"mode": "test",
"organization_id": "xRRkjDFafe",
"trace_id": "69abaa3545913c78132e5578bd26208d44aa9043647d78698fd0021f3958cd74"
},
"links": {
"first": "https://yourdomain.commercelayer.io/api/stock_items?filter[q][low_stock]=true&page[number]=1&page[size]=10",
"last": "https://yourdomain.commercelayer.io/api/stock_items?filter[q][low_stock]=true&page[number]=1&page[size]=10"
}
}
{% endtab %}
{% endtabs %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.commercelayer.io/core-api-reference/stock_items.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.