Variants
Index
To return a paginated list of all variants within the store, make this request:
GET /api/v1/variantsYou can limit this to showing the variants for a particular product by passing through a product’s slug:
GET /api/v1/products/ruby-on-rails-tote/variantsor
GET /api/v1/variants?product_id=ruby-on-rails-toteParameters
- show_deleted:
boolean -
trueto show deleted variants,falseto hide them. Default:false. Only available to users with an admin role.- page:
The page number of variants to display.
- per_page:
The number of variants to return per page
Response
Status:
200 OK
{"variants": [{"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,"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,"total_count": 25,"current_page": 1,"pages": 1}
Search
To search for a particular variant, make a request like this:
GET /api/v1/variants?q[sku_cont]=fooYou can limit this to showing the variants for a particular product by passing through a product id:
GET /api/v1/products/ruby-on-rails-tote/variants?q[sku_cont]=fooor
GET /api/v1/variants?product_id=ruby-on-rails-tote&q[sku_cont]=fooThe searching API is provided through the Ransack gem which Spree depends on. The sku_cont 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
{"variants": [{"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,"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": 1,"total_count": 1,"current_page": 1,"pages": 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/variants?q[s]=price%20ascIt is also possible to sort results using an associated object’s field.
GET /api/v1/variants?q[s]=product_name%20ascShow
To view the details for a single variant, make a request using that variant’s id, along with the product’s permalink as its product_id:
GET /api/v1/products/ruby-on-rails-tote/variants/1Or:
GET /api/v1/variants/1?product_id=ruby-on-rails-toteSuccessful Response
Status:
200 OK
{"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."}
New
You can learn about the potential attributes (required and non-required) for a variant by making this request:
GET /api/v1/products/ruby-on-rails-tote/variants/newResponse
Status:
200 OK
{
"attributes": [
"id", "name", "sku", "price", "weight", "height",
"width", "depth", "is_master", "slug", "description", "track_inventory"
],
"required_attributes": []
}Create
This action is only accessible by an admin user.
To create a new variant for a product, make this request with the necessary parameters:
POST /api/v1/products/ruby-on-rails-tote/variantsFor instance, a request to create a new variant with a SKU of 12345 and a price of 19.99 would look like this::
POST /api/v1/products/ruby-on-rails-tote/variants/?variant[sku]=12345&variant[price]=19.99&variant[option_value_ids][]=1Successful response
Status:
201 Created
{"id": 1,"name": "Ruby on Rails Tote","sku": "12345","price": 19.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,"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}}]}
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.
To update a variant’s details, make this request with the necessary parameters:
PUT /api/v1/products/ruby-on-rails-tote/variants/2For instance, to update a variant’s SKU, send it through like this:
PUT /api/v1/products/ruby-on-rails-tote/variants/2?variant[sku]=12345Successful response
Status:
201 Created
{"id": 1,"name": "Ruby on Rails Tote","sku": "12345","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,"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}}]}
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 variant, make this request:
DELETE /api/v1/products/ruby-on-rails-tote/variants/2This request, much like a typical variant ”deletion” through the admin interface, will not actually remove the record from the database. It simply sets the deleted_at field to the current time on the variant.
Status:
204 No Content