APIExtensionsDeveloperUserReleasesDemoSupport
  • V 1

    • Summary
    • Address
    • Checkouts
    • Countries
    • Customer Returns
    • Line Items
    • Option Types
    • Option Values
    • Orders
    • Payments
    • Product Images
    • Product Properties
    • Products
    • Return Authorizations
    • Shipments
    • States
    • Stock Items
    • Stock Locations
    • Stock Movements
    • Taxonomies
    • Users
    • Variants
    • Zones

Table Of Contents

IndexParametersResponseSearchResponseSorting resultsShowSuccessful ResponseNot Found ResponseNewResponseCreateSuccessful responseFailed responseUpdateSuccessful responseFailed responseDelete

Variants

Index

To return a paginated list of all variants within the store, make this request:

GET /api/v1/variants

You 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/variants

or

GET /api/v1/variants?product_id=ruby-on-rails-tote

Parameters

show_deleted:

boolean - true to show deleted variants, false to 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]=foo

You 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]=foo

or

GET /api/v1/variants?product_id=ruby-on-rails-tote&q[sku_cont]=foo

The 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%20asc

It is also possible to sort results using an associated object’s field.

GET /api/v1/variants?q[s]=product_name%20asc

Show

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/1

Or:

GET /api/v1/variants/1?product_id=ruby-on-rails-tote

Successful 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/new

Response

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/variants

For 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][]=1

Successful 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/2

For instance, to update a variant’s SKU, send it through like this:

PUT /api/v1/products/ruby-on-rails-tote/variants/2?variant[sku]=12345

Successful 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/2

This 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
Propose changes to this page
Maintained bySpree Commerce & Ruby on Rails developers© Spree Commerce. 2021 All Rights Reserved.