Stock Items

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,
      "stock_location_id": 1,
      "variant_id": 1,
      "variant": {
        "id": 1,
        "name": "Ruby on Rails Tote",
        "sku": "ROR-00011",
        "price": "15.99",
        "weight": null,
        "height": null,
        "width": null,
        "depth": null,
        "is_master": true,
        "slug": "ruby-on-rails-tote",
        "description": "A text description of the product.",
        "track_inventory": true,
        "cost_price": null,
        "option_values": [
          {
            "id": 1,
            "name": "Small",
            "presentation": "S",
            "option_type_name": "tshirt-size",
            "option_type_id": 1,
            "option_type_presentation": "S"
          }
        ],
        "images": [
          {
            "id": 1,
            "position": 1,
            "attachment_content_type": "image/jpg",
            "attachment_file_name": "ror_tote.jpeg",
            "type": "Spree::Image",
            "attachment_updated_at": null,
            "attachment_width": 360,
            "attachment_height": 360,
            "alt": null,
            "viewable_type": "Spree::Variant",
            "viewable_id": 1,
            "mini_url": "/spree/products/1/mini/file.png?1370533476",
            "small_url": "/spree/products/1/small/file.png?1370533476",
            "product_url": "/spree/products/1/product/file.png?1370533476",
            "large_url": "/spree/products/1/large/file.png?1370533476"
          }
        ],
        "display_price": "$15.99",
        "options_text": "(Size: small, Colour: red)",
        "in_stock": true,
        "is_backorderable": true,
        "is_orderable": true,
        "total_on_hand": 10,
        "is_destroyed": false
      }
    }
  ],
  "count": 25,
  "current_page": 1,
  "pages": 5
}

Search

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 Boxid 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,
      "stock_location_id": 1,
      "variant_id": 1,
      "variant": {
        "id": 1,
        "name": "Ruby on Rails Tote",
        "sku": "ROR-00011",
        "price": "15.99",
        "weight": null,
        "height": null,
        "width": null,
        "depth": null,
        "is_master": true,
        "slug": "ruby-on-rails-tote",
        "description": "A text description of the product.",
        "track_inventory": true,
        "cost_price": null,
        "option_values": [
          {
            "id": 1,
            "name": "Small",
            "presentation": "S",
            "option_type_name": "tshirt-size",
            "option_type_id": 1,
            "option_type_presentation": "S"
          }
        ],
        "images": [
          {
            "id": 1,
            "position": 1,
            "attachment_content_type": "image/jpg",
            "attachment_file_name": "ror_tote.jpeg",
            "type": "Spree::Image",
            "attachment_updated_at": null,
            "attachment_width": 360,
            "attachment_height": 360,
            "alt": null,
            "viewable_type": "Spree::Variant",
            "viewable_id": 1,
            "mini_url": "/spree/products/1/mini/file.png?1370533476",
            "small_url": "/spree/products/1/small/file.png?1370533476",
            "product_url": "/spree/products/1/product/file.png?1370533476",
            "large_url": "/spree/products/1/large/file.png?1370533476"
          }
        ],
        "display_price": "$15.99",
        "options_text": "(Size: small, Colour: red)",
        "in_stock": true,
        "is_backorderable": true,
        "is_orderable": true,
        "total_on_hand": 10,
        "is_destroyed": false
      }
    }
  ],
  "count": 25,
  "current_page": 1,
  "pages": 5
}

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,
  "stock_location_id": 1,
  "variant_id": 1,
  "variant": {
    "id": 1,
    "name": "Ruby on Rails Tote",
    "sku": "ROR-00011",
    "price": "15.99",
    "weight": null,
    "height": null,
    "width": null,
    "depth": null,
    "is_master": true,
    "slug": "ruby-on-rails-tote",
    "description": "A text description of the product.",
    "track_inventory": true,
    "cost_price": null,
    "option_values": [
      {
        "id": 1,
        "name": "Small",
        "presentation": "S",
        "option_type_name": "tshirt-size",
        "option_type_id": 1,
        "option_type_presentation": "S"
      }
    ],
    "images": [
      {
        "id": 1,
        "position": 1,
        "attachment_content_type": "image/jpg",
        "attachment_file_name": "ror_tote.jpeg",
        "type": "Spree::Image",
        "attachment_updated_at": null,
        "attachment_width": 360,
        "attachment_height": 360,
        "alt": null,
        "viewable_type": "Spree::Variant",
        "viewable_id": 1,
        "mini_url": "/spree/products/1/mini/file.png?1370533476",
        "small_url": "/spree/products/1/small/file.png?1370533476",
        "product_url": "/spree/products/1/product/file.png?1370533476",
        "large_url": "/spree/products/1/large/file.png?1370533476"
      }
    ],
    "display_price": "$15.99",
    "options_text": "(Size: small, Colour: red)",
    "in_stock": true,
    "is_backorderable": true,
    "is_orderable": true,
    "total_on_hand": 10,
    "is_destroyed": false
  }
}

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 countonhand 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,
  "stock_location_id": 1,
  "variant_id": 1,
  "variant": {
    "id": 1,
    "name": "Ruby on Rails Tote",
    "sku": "ROR-00011",
    "price": "15.99",
    "weight": null,
    "height": null,
    "width": null,
    "depth": null,
    "is_master": true,
    "slug": "ruby-on-rails-tote",
    "description": "A text description of the product.",
    "track_inventory": true,
    "cost_price": null,
    "option_values": [
      {
        "id": 1,
        "name": "Small",
        "presentation": "S",
        "option_type_name": "tshirt-size",
        "option_type_id": 1,
        "option_type_presentation": "S"
      }
    ],
    "images": [
      {
        "id": 1,
        "position": 1,
        "attachment_content_type": "image/jpg",
        "attachment_file_name": "ror_tote.jpeg",
        "type": "Spree::Image",
        "attachment_updated_at": null,
        "attachment_width": 360,
        "attachment_height": 360,
        "alt": null,
        "viewable_type": "Spree::Variant",
        "viewable_id": 1,
        "mini_url": "/spree/products/1/mini/file.png?1370533476",
        "small_url": "/spree/products/1/small/file.png?1370533476",
        "product_url": "/spree/products/1/product/file.png?1370533476",
        "large_url": "/spree/products/1/large/file.png?1370533476"
      }
    ],
    "display_price": "$15.99",
    "options_text": "(Size: small, Colour: red)",
    "in_stock": true,
    "is_backorderable": true,
    "is_orderable": true,
    "total_on_hand": 10,
    "is_destroyed": false
  }
}

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, countonhand IS APPENDED to its current value.

Sending a request with a negative countonhand WILL SUBSTRACT the current value.

To force a value for countonhand, 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 countonhand, send it through like this:

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

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

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

Successful response

Status:

201 Created

{
  "id": 1,
  "count_on_hand": 30,
  "backorderable": true,
  "stock_location_id": 1,
  "variant_id": 1,
  "variant": {
    "id": 1,
    "name": "Ruby on Rails Tote",
    "sku": "ROR-00011",
    "price": "15.99",
    "weight": null,
    "height": null,
    "width": null,
    "depth": null,
    "is_master": true,
    "slug": "ruby-on-rails-tote",
    "description": "A text description of the product.",
    "track_inventory": true,
    "cost_price": null,
    "option_values": [
      {
        "id": 1,
        "name": "Small",
        "presentation": "S",
        "option_type_name": "tshirt-size",
        "option_type_id": 1,
        "option_type_presentation": "S"
      }
    ],
    "images": [
      {
        "id": 1,
        "position": 1,
        "attachment_content_type": "image/jpg",
        "attachment_file_name": "ror_tote.jpeg",
        "type": "Spree::Image",
        "attachment_updated_at": null,
        "attachment_width": 360,
        "attachment_height": 360,
        "alt": null,
        "viewable_type": "Spree::Variant",
        "viewable_id": 1,
        "mini_url": "/spree/products/1/mini/file.png?1370533476",
        "small_url": "/spree/products/1/small/file.png?1370533476",
        "product_url": "/spree/products/1/product/file.png?1370533476",
        "large_url": "/spree/products/1/large/file.png?1370533476"
      }
    ],
    "display_price": "$15.99",
    "options_text": "(Size: small, Colour: red)",
    "in_stock": true,
    "is_backorderable": true,
    "is_orderable": true,
    "total_on_hand": 10,
    "is_destroyed": false
  }
}

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

Edit this page on GitHub