Product Variant

Important

After July 1st, apps will no longer be able to set inventory using `inventory_quantity` or `inventory_quantity_adjustment`.

Learn More.

A variant can be added to a Product resource to represent one version of a product with several options. The Product resource will have a variant for every possible combination of its options. Each product can have a maximum of three options and a maximum of 100 variants.

What you can do with Product Variant

The Shopify API lets you do the following with the Product Variant resource. More detailed versions of these general actions may be available:

Product Variant properties

barcode
"barcode": "1234_pink"

The barcode, UPC, or ISBN number for the product.

compare_at_price
"compare_at_price": "299.00"

The original price of the item before an adjustment or a sale.

created_at
"created_at": "2012-08-24T14:01:47-04:00"

The date and time (ISO 8601 format) when the product variant was created.

fulfillment_service
"fulfillment_service": "manual"

The fulfillment service associated with the product variant. Valid values: manual or the handle of a fulfillment service.

grams
"grams": 567

The weight of the product variant in grams.

id
"id": 808950810

The unique numeric identifier for the product variant.

image_id
"image_id": 434522

The unique numeric identifier for a product's image. The image must be associated to the same product as the variant.

inventory_item_id
"inventory_item_id": 342916

The unique identifier for the inventory item, which is used in the Inventory API to query for inventory information.

inventory_management
"inventory_management": "shopify"

The fulfillment service that tracks the number of items in stock for the product variant. If you track the inventory yourself using the admin, then set the value to "shopify". Valid values: shopify or the handle of a fulfillment service that has inventory management enabled. Must be the same fulfillment service referenced by the fulfillment_service property.

inventory_policy
"inventory_policy": "continue"

Whether customers are allowed to place an order for the product variant when it's out of stock. Valid values:

  • deny: Customers are not allowed to place orders for the product variant if it's out of stock.
  • continue: Customers are allowed to place orders for the product variant if it's out of stock.
Default value: deny.

inventory_quantity
deprecated
"inventory_quantity": 10

The total available quantity of inventory across all locations. When used to update inventory, inventory_quantity adjusts a product variant's inventory at its location that has the lowest ID. The inventory at that location will be adjusted so that the sum of inventory across all locations matches the set value.

Use the Inventory Level endpoint instead.

old_inventory_quantity
deprecated
"old_inventory_quantity": 5

The last stock level that you saw for the product variant. This should be sent when changing the inventory_quantity to avoid a race condition when the item being adjusted is simultaneously sold online.

Use the Inventory Level endpoint instead.

inventory_quantity_adjustment
deprecated
"inventory_quantity_adjustment": 5

Adjusts a product variant's inventory at its location that has the lowest ID. This property takes precedence over inventory_quantity.

Use the Inventory Level endpoint instead.

metafields
"metafields": [
  {
    "key": "new",
    "value": "newvalue",
    "value_type": "string",
    "namespace": "global"
  }
]

Additional customizable information about the product variant.

  • key: Required. The identifier for the metafield. (maximum: 30 characters)
  • namespace: Required. The container for a set of metadata. You need to define a custom namespace for your metafields to distinguish them from metafields used by other apps. (maximum: 20 characters)
  • value: Required. The information to be stored as metadata.
  • value_type: Required. The type of information that the metafield contains. Valid values: string, integer
  • description: Additional information about the metafield.

option
"option1": "Pink"

The custom properties that a shop owner uses to define product variants. You can define three options for a product: option1, option2, option3. Default value: Default Title.

position
"position": 1

The order of the product variant in the list of product variants. The first position in the list is 1.

price
"price": "199.00"

The price of the product variant.

product_id
"product_id": 632910392

The unique numeric identifier for the product.

requires_shipping
"requires_shipping": true

Whether a customer needs to provide a shipping address when placing an order for the product variant.

sku
"sku": "IPOD2008PINK"

A unique identifier for the product variant in the shop. Required in order to connect to a FulfillmentService.

taxable
"taxable": true

Whether a tax is charged when the product variant is sold.

tax_code
"tax_code": "DA040000"

This parameter applies only to the stores that have the Avalara AvaTax app installed. Specifies the Avalara tax code for the product variant.

title
"title": "Pink"

The title of the product variant.

updated_at
"updated_at": "2012-08-24T14:01:47-04:00"

The date and time when the product variant was last modified. Gets returned in ISO 8601 format.

weight
"weight": 100

The weight of the product variant in the unit system specified with weight_unit.

weight_unit
"weight_unit": "oz"

The unit of measurement that applies to the product variant's weight. If you don't specify a value for weight_unit, then the shop's default unit of measurement is applied. Valid values: g, kg, oz, and lb.

Endpoints

GET /admin/products/632910392/variants.json
Retrieves a list of product variants
limit

Return up to this many results per page

(default: 50) (maximum: 250)
page

Return a specific page of results

(default: 1)
since_id

Restrict results to after the specified ID

fields

A comma-separated list of fields to include in the response

Retrieve all variants for a product

GET /admin/products/#{product_id}/variants.json
View Response
HTTP/1.1 200 OK
{
  "variants": [
    {
      "id": 808950810,
      "product_id": 632910392,
      "title": "Pink",
      "price": "199.00",
      "sku": "IPOD2008PINK",
      "position": 1,
      "inventory_policy": "continue",
      "compare_at_price": null,
      "fulfillment_service": "manual",
      "inventory_management": "shopify",
      "option1": "Pink",
      "option2": null,
      "option3": null,
      "created_at": "2018-04-17T13:23:45-04:00",
      "updated_at": "2018-04-17T13:23:45-04:00",
      "taxable": true,
      "barcode": "1234_pink",
      "grams": 567,
      "image_id": 562641783,
      "inventory_quantity": 10,
      "weight": 1.25,
      "weight_unit": "lb",
      "inventory_item_id": 808950810,
      "old_inventory_quantity": 10,
      "requires_shipping": true
    },
    {
      "id": 49148385,
      "product_id": 632910392,
      "title": "Red",
      "price": "199.00",
      "sku": "IPOD2008RED",
      "position": 2,
      "inventory_policy": "continue",
      "compare_at_price": null,
      "fulfillment_service": "manual",
      "inventory_management": "shopify",
      "option1": "Red",
      "option2": null,
      "option3": null,
      "created_at": "2018-04-17T13:23:45-04:00",
      "updated_at": "2018-04-17T13:23:45-04:00",
      "taxable": true,
      "barcode": "1234_red",
      "grams": 567,
      "image_id": null,
      "inventory_quantity": 20,
      "weight": 1.25,
      "weight_unit": "lb",
      "inventory_item_id": 49148385,
      "old_inventory_quantity": 20,
      "requires_shipping": true
    },
    {
      "id": 39072856,
      "product_id": 632910392,
      "title": "Green",
      "price": "199.00",
      "sku": "IPOD2008GREEN",
      "position": 3,
      "inventory_policy": "continue",
      "compare_at_price": null,
      "fulfillment_service": "manual",
      "inventory_management": "shopify",
      "option1": "Green",
      "option2": null,
      "option3": null,
      "created_at": "2018-04-17T13:23:45-04:00",
      "updated_at": "2018-04-17T13:23:45-04:00",
      "taxable": true,
      "barcode": "1234_green",
      "grams": 567,
      "image_id": null,
      "inventory_quantity": 30,
      "weight": 1.25,
      "weight_unit": "lb",
      "inventory_item_id": 39072856,
      "old_inventory_quantity": 30,
      "requires_shipping": true
    },
    {
      "id": 457924702,
      "product_id": 632910392,
      "title": "Black",
      "price": "199.00",
      "sku": "IPOD2008BLACK",
      "position": 4,
      "inventory_policy": "continue",
      "compare_at_price": null,
      "fulfillment_service": "manual",
      "inventory_management": "shopify",
      "option1": "Black",
      "option2": null,
      "option3": null,
      "created_at": "2018-04-17T13:23:45-04:00",
      "updated_at": "2018-04-17T13:23:45-04:00",
      "taxable": true,
      "barcode": "1234_black",
      "grams": 567,
      "image_id": null,
      "inventory_quantity": 40,
      "weight": 1.25,
      "weight_unit": "lb",
      "inventory_item_id": 457924702,
      "old_inventory_quantity": 40,
      "requires_shipping": true
    }
  ]
}

Retrieve all variants for a product after a specified ID

GET /admin/products/#{product_id}/variants.json?since_id=49148385
View Response
HTTP/1.1 200 OK
{
  "variants": [
    {
      "id": 457924702,
      "product_id": 632910392,
      "title": "Black",
      "price": "199.00",
      "sku": "IPOD2008BLACK",
      "position": 4,
      "inventory_policy": "continue",
      "compare_at_price": null,
      "fulfillment_service": "manual",
      "inventory_management": "shopify",
      "option1": "Black",
      "option2": null,
      "option3": null,
      "created_at": "2018-04-17T13:23:45-04:00",
      "updated_at": "2018-04-17T13:23:45-04:00",
      "taxable": true,
      "barcode": "1234_black",
      "grams": 567,
      "image_id": null,
      "inventory_quantity": 40,
      "weight": 1.25,
      "weight_unit": "lb",
      "inventory_item_id": 457924702,
      "old_inventory_quantity": 40,
      "requires_shipping": true
    },
    {
      "id": 808950810,
      "product_id": 632910392,
      "title": "Pink",
      "price": "199.00",
      "sku": "IPOD2008PINK",
      "position": 1,
      "inventory_policy": "continue",
      "compare_at_price": null,
      "fulfillment_service": "manual",
      "inventory_management": "shopify",
      "option1": "Pink",
      "option2": null,
      "option3": null,
      "created_at": "2018-04-17T13:23:45-04:00",
      "updated_at": "2018-04-17T13:23:45-04:00",
      "taxable": true,
      "barcode": "1234_pink",
      "grams": 567,
      "image_id": 562641783,
      "inventory_quantity": 10,
      "weight": 1.25,
      "weight_unit": "lb",
      "inventory_item_id": 808950810,
      "old_inventory_quantity": 10,
      "requires_shipping": true
    }
  ]
}
GET /admin/products/632910392/variants/count.json
Retrieves a count of product variants

Retrieve a count all variants for a product

GET /admin/products/#{product_id}/variants/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 4
}
GET /admin/variants/808950810.json
Retrieves a single product variant by ID
fields

A comma-separated list of fields to include in the response

Retrieve a product variant by ID

GET /admin/variants/#{variant_id}.json
View Response
HTTP/1.1 200 OK
{
  "variant": {
    "id": 808950810,
    "product_id": 632910392,
    "title": "Pink",
    "price": "199.00",
    "sku": "IPOD2008PINK",
    "position": 1,
    "inventory_policy": "continue",
    "compare_at_price": null,
    "fulfillment_service": "manual",
    "inventory_management": "shopify",
    "option1": "Pink",
    "option2": null,
    "option3": null,
    "created_at": "2018-04-17T13:23:45-04:00",
    "updated_at": "2018-04-17T13:23:45-04:00",
    "taxable": true,
    "barcode": "1234_pink",
    "grams": 567,
    "image_id": 562641783,
    "inventory_quantity": 10,
    "weight": 1.25,
    "weight_unit": "lb",
    "inventory_item_id": 808950810,
    "tax_code": "DA040000",
    "old_inventory_quantity": 10,
    "requires_shipping": true
  }
}
POST /admin/products/632910392/variants.json
Creates a new product variant

Create a new product variant

POST /admin/products/#{product_id}/variants.json
{
  "variant": {
    "option1": "Yellow",
    "price": "1.00"
  }
}
View Response
HTTP/1.1 201 Created
{
  "variant": {
    "id": 1070325020,
    "product_id": 632910392,
    "title": "Yellow",
    "price": "1.00",
    "sku": "",
    "position": 5,
    "inventory_policy": "deny",
    "compare_at_price": null,
    "fulfillment_service": "manual",
    "inventory_management": null,
    "option1": "Yellow",
    "option2": null,
    "option3": null,
    "created_at": "2018-04-17T13:25:02-04:00",
    "updated_at": "2018-04-17T13:25:02-04:00",
    "taxable": true,
    "barcode": null,
    "grams": 0,
    "image_id": null,
    "inventory_quantity": 1,
    "weight": 0.0,
    "weight_unit": "lb",
    "inventory_item_id": 1070325020,
    "old_inventory_quantity": 1,
    "requires_shipping": true
  }
}

Create a new product variant with a metafield

POST /admin/products/#{product_id}/variants.json
{
  "variant": {
    "option1": "Blue",
    "metafields": [
      {
        "key": "new",
        "value": "newvalue",
        "value_type": "string",
        "namespace": "global"
      }
    ]
  }
}
View Response
HTTP/1.1 201 Created
{
  "variant": {
    "id": 1070325021,
    "product_id": 632910392,
    "title": "Blue",
    "price": "0.00",
    "sku": "",
    "position": 5,
    "inventory_policy": "deny",
    "compare_at_price": null,
    "fulfillment_service": "manual",
    "inventory_management": null,
    "option1": "Blue",
    "option2": null,
    "option3": null,
    "created_at": "2018-04-17T13:25:03-04:00",
    "updated_at": "2018-04-17T13:25:03-04:00",
    "taxable": true,
    "barcode": null,
    "grams": 0,
    "image_id": null,
    "inventory_quantity": 1,
    "weight": 0.0,
    "weight_unit": "lb",
    "inventory_item_id": 1070325021,
    "old_inventory_quantity": 1,
    "requires_shipping": true
  }
}

Create a new product variant with an image

POST /admin/products/#{product_id}/variants.json
{
  "variant": {
    "image_id": 850703190,
    "option1": "Purple"
  }
}
View Response
HTTP/1.1 201 Created
{
  "variant": {
    "id": 1070325022,
    "product_id": 632910392,
    "title": "Purple",
    "price": "0.00",
    "sku": "",
    "position": 5,
    "inventory_policy": "deny",
    "compare_at_price": null,
    "fulfillment_service": "manual",
    "inventory_management": null,
    "option1": "Purple",
    "option2": null,
    "option3": null,
    "created_at": "2018-04-17T13:25:03-04:00",
    "updated_at": "2018-04-17T13:25:03-04:00",
    "taxable": true,
    "barcode": null,
    "grams": 0,
    "image_id": 850703190,
    "inventory_quantity": 1,
    "weight": 0.0,
    "weight_unit": "lb",
    "inventory_item_id": 1070325022,
    "old_inventory_quantity": 1,
    "requires_shipping": true
  }
}
PUT /admin/variants/808950810.json
Updates an existing product variant

Update the title and price of an existing variant

PUT /admin/variants/#{variant_id}.json
{
  "variant": {
    "id": 808950810,
    "option1": "Not Pink",
    "price": "99.00"
  }
}
View Response
HTTP/1.1 200 OK
{
  "variant": {
    "id": 808950810,
    "product_id": 632910392,
    "title": "Not Pink",
    "price": "99.00",
    "sku": "IPOD2008PINK",
    "position": 1,
    "inventory_policy": "continue",
    "compare_at_price": null,
    "fulfillment_service": "manual",
    "inventory_management": "shopify",
    "option1": "Not Pink",
    "option2": null,
    "option3": null,
    "created_at": "2018-04-17T13:23:45-04:00",
    "updated_at": "2018-04-17T13:25:04-04:00",
    "taxable": true,
    "barcode": "1234_pink",
    "grams": 567,
    "image_id": 562641783,
    "inventory_quantity": 10,
    "weight": 1.25,
    "weight_unit": "lb",
    "inventory_item_id": 808950810,
    "old_inventory_quantity": 10,
    "requires_shipping": true
  }
}

Update a variant's inventory using an adjustment

PUT /admin/variants/#{variant_id}.json
{
  "variant": {
    "id": 808950810,
    "inventory_quantity_adjustment": -5
  }
}
View Response
HTTP/1.1 200 OK
{
  "variant": {
    "id": 808950810,
    "product_id": 632910392,
    "title": "Pink",
    "price": "199.00",
    "sku": "IPOD2008PINK",
    "position": 1,
    "inventory_policy": "continue",
    "compare_at_price": null,
    "fulfillment_service": "manual",
    "inventory_management": "shopify",
    "option1": "Pink",
    "option2": null,
    "option3": null,
    "created_at": "2018-04-17T13:23:45-04:00",
    "updated_at": "2018-04-17T13:25:05-04:00",
    "taxable": true,
    "barcode": "1234_pink",
    "grams": 567,
    "image_id": 562641783,
    "inventory_quantity": 5,
    "weight": 1.25,
    "weight_unit": "lb",
    "inventory_item_id": 808950810,
    "old_inventory_quantity": 5,
    "requires_shipping": true
  }
}

Update a variant's inventory

PUT /admin/variants/#{variant_id}.json
{
  "variant": {
    "id": 808950810,
    "inventory_quantity": 100,
    "old_inventory_quantity": 10
  }
}
View Response
HTTP/1.1 200 OK
{
  "variant": {
    "id": 808950810,
    "product_id": 632910392,
    "title": "Pink",
    "price": "199.00",
    "sku": "IPOD2008PINK",
    "position": 1,
    "inventory_policy": "continue",
    "compare_at_price": null,
    "fulfillment_service": "manual",
    "inventory_management": "shopify",
    "option1": "Pink",
    "option2": null,
    "option3": null,
    "created_at": "2018-04-17T13:23:45-04:00",
    "updated_at": "2018-04-17T13:25:05-04:00",
    "taxable": true,
    "barcode": "1234_pink",
    "grams": 567,
    "image_id": 562641783,
    "inventory_quantity": 100,
    "weight": 1.25,
    "weight_unit": "lb",
    "inventory_item_id": 808950810,
    "old_inventory_quantity": 100,
    "requires_shipping": true
  }
}

Add a metafield to an existing variant

PUT /admin/variants/#{variant_id}.json
{
  "variant": {
    "id": 808950810,
    "metafields": [
      {
        "key": "new",
        "value": "newvalue",
        "value_type": "string",
        "namespace": "global"
      }
    ]
  }
}
View Response
HTTP/1.1 200 OK
{
  "variant": {
    "id": 808950810,
    "product_id": 632910392,
    "title": "Pink",
    "price": "199.00",
    "sku": "IPOD2008PINK",
    "position": 1,
    "inventory_policy": "continue",
    "compare_at_price": null,
    "fulfillment_service": "manual",
    "inventory_management": "shopify",
    "option1": "Pink",
    "option2": null,
    "option3": null,
    "created_at": "2018-04-17T13:23:45-04:00",
    "updated_at": "2018-04-17T13:25:06-04:00",
    "taxable": true,
    "barcode": "1234_pink",
    "grams": 567,
    "image_id": 562641783,
    "inventory_quantity": 10,
    "weight": 1.25,
    "weight_unit": "lb",
    "inventory_item_id": 808950810,
    "old_inventory_quantity": 10,
    "requires_shipping": true
  }
}

Add an existing image to an existing variant

PUT /admin/variants/#{variant_id}.json
{
  "variant": {
    "id": 808950810,
    "image_id": 562641783
  }
}
View Response
HTTP/1.1 200 OK
{
  "variant": {
    "id": 808950810,
    "product_id": 632910392,
    "title": "Pink",
    "price": "199.00",
    "sku": "IPOD2008PINK",
    "position": 1,
    "inventory_policy": "continue",
    "compare_at_price": null,
    "fulfillment_service": "manual",
    "inventory_management": "shopify",
    "option1": "Pink",
    "option2": null,
    "option3": null,
    "created_at": "2018-04-17T13:23:45-04:00",
    "updated_at": "2018-04-17T13:25:06-04:00",
    "taxable": true,
    "barcode": "1234_pink",
    "grams": 567,
    "image_id": 562641783,
    "inventory_quantity": 10,
    "weight": 1.25,
    "weight_unit": "lb",
    "inventory_item_id": 808950810,
    "old_inventory_quantity": 10,
    "requires_shipping": true
  }
}
DELETE /admin/products/632910392/variants/808950810.json

Delete a product variant

DELETE /admin/products/#{product_id}/variants/#{variant_id}.json
View Response
HTTP/1.1 200 OK
{
}