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
}

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