Index

This action is only accessible by an admin user.

To return a paginated list of all stock items for a stock location, make this request, passing the stock location id you wish to see stock items for:

GET /api/v1/stock_locations/1/stock_items

Parameters

page
The page number of stock items to display.
per_page
The number of stock items to return per page

Response

Status: 200 OK
{
  "stock_items": [
    {
      "id": 1,
      "count_on_hand": 10,
      "backorderable": true,
      "lock_version": 1,
      "stock_location_id": 1,
      "variant_id": 1
    }
  ],
  "count": 25,
  "pages": 5,
  "current_page": 1
}
This action is only accessible by an admin user.

To search for a particular stock item, make a request like this:

GET /api/v1/stock_locations/1/stock_items?q[variant_id_eq]=10

The searching API is provided through the Ransack gem which Spree depends on. The variant_id_eq here is called a predicate, and you can learn more about them by reading about Predicates on the Ransack wiki.

The search results are paginated.

Response

Status: 200 OK
{
  "stock_items": [
    {
      "id": 1,
      "count_on_hand": 10,
      "backorderable": true,
      "lock_version": 1,
      "stock_location_id": 1,
      "variant_id": 1
    }
  ],
  "count": 25,
  "pages": 5,
  "current_page": 1
}

Sorting results

Results can be returned in a specific order by specifying which field to sort by when making a request.

GET /api/v1/stock_locations/1/stock_items?q[s]=variant_id%20asc

Show

This action is only accessible by an admin user.

To view the details for a single stock item, make a request using that stock item’s id, along with its stock_location_id:

GET /api/v1/stock_locations/1/stock_items/2

Successful Response

Status: 200 OK
{
  "id": 1,
  "count_on_hand": 10,
  "backorderable": true,
  "lock_version": 1,
  "stock_location_id": 1,
  "variant_id": 1
}

Not Found Response

Status: 404 Not Found
{
  "error": "The resource you were looking for could not be found."
}

Create

This action is only accessible by an admin user.

To create a new stock item for a stock location, make this request with the necessary parameters:

POST /api/v1/stock_locations/1/stock_items

For instance, a request to create a new stock item with a count_on_hand of 10 and a variant_id of 1 would look like this::

{
  "stock_item": {
    "count_on_hand": "10",
    "variant_id": "1",
    "backorderable": "true"
  }
}

Successful response

Status: 201 Created
{
  "id": 1,
  "count_on_hand": 10,
  "backorderable": true,
  "lock_version": 1,
  "stock_location_id": 1,
  "variant_id": 1
}

Failed response

Status: 422 Unprocessable Entity
{
  "error": "Invalid resource. Please fix errors and try again.",
  "errors": {

  }
}

Update

This action is only accessible by an admin user.

Note that using this endpoint, count_on_hand is APPENDED to its current value.

Sending a request with a negative count_on_hand will subtract the current value.

To force a value for count_on_hand, include force: true in your request, this will replace the current value as it’s stored in the database.

To update a stock item’s details, make this request with the necessary parameters.

PUT /api/v1/stock_locations/1/stock_items/2

For instance, to update a stock item’s count_on_hand, send it through like this:

{
  "stock_item": {
    "count_on_hand": "30"
  }
}

Or alternatively with the force attribute to replace the current count_on_hand with a new value:

{
  "stock_item": {
    "count_on_hand": "30",
    "force": true
  }
}

Successful response

Status: 201 Created
{
  "id": 1,
  "count_on_hand": 10,
  "backorderable": true,
  "lock_version": 1,
  "stock_location_id": 1,
  "variant_id": 1
}

Failed response

Status: 422 Unprocessable Entity
{
  "error": "Invalid resource. Please fix errors and try again.",
  "errors": {

  }
}

Delete

This action is only accessible by an admin user.

To delete a stock item, make this request:

DELETE /api/v1/stock_locations/1/stock_items/2

Response

Status: 204 No Content