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 in a given stock location.

The actual availability of an item may vary depending on active stock reservations. If active stock reservations are associated with a stock item, the available quantity equals the stock item quantity minus the reserved stock quantity.

When you place an order 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 is approved and the associated items are restocked, the stock item quantities get incremented.

When updating stock items quantities via imports, 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.

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.

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.

Request

The following request fetches all the stock items that are currently low on stock:

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'

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"
  }
}