Index
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/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
}Search
To search for a particular stock item, make a request like this:
GET /api/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/stock_locations/1/stock_items?q[s]=variant_id%20asc
Show
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/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
To create a new stock item for a stock location, make this request with the necessary parameters:
POST /api/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
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/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
To delete a stock item, make this request:
DELETE /api/stock_locations/1/stock_items/2
Response
Status: 204 No Content