Product Variant (API)

From Shopify Wiki

A product variant (or variant for short) is a different version of a product, such as a size or a color. Without variants, you would have to treat the small, medium and large versions of a t-shirt as three separate products; variants let you treat the small, medium and large versions of a t-shirt as variations of the same product.

For a full explanation of variants, see Products, variants and options in the documentation of the product resource.

1 Variant properties
2 How to get a list of a product's variants
- 2.1 JSON
- 2.2 XML
3 How to get a single product variant
- 3.1 JSON
- 3.2 XML
4 How to add a new product variant
- 4.1 JSON
- 4.2 XML
5 How to modify a product variant
- 5.1 Updating the inventory count of a variant
  - 5.1.1 JSON
  - 5.1.2 XML
6 How to delete a product variant
- 6.1 JSON
- 6.2 XML

Variant properties

compare-at-price (optional)

The "compare at price" — usually the price that a competitor is charging for the same item or the price you used to charge for the item. Ideally, this value should be higher than the price you're currently charging.

created-at

The date and time when the variant was created.

fulfillment-service

grams

The weight of the variant, expressed in grams. In case you're working in ounces, 1 gram = 0.0353 ounces; 1 ounce = 28.35 grams.

id

The unique numeric identifier for the variant.

inventory-management

Specifies whether or not Shopify tracks the number of items in stock for this variant. This can take on one of two values:

blank: Indicates that Shopify does not track the number of items in stock for this variant.
shopify: Indicates that Shopify tracks the number of items in stock for this variant.

In the admin panel, this value is set by using the Inventory drop-down menu when editing the variant.

inventory-policy

Specifies whether or not customers are allowed to place orders for the variant when it's out of stock. Applicable only when the value of inventory-management is set to shopify. This can take on one of two values:

deny (default): Indicates that customers are not allowed to place orders for the variant when it's out of stock.
continue : Indicates that customers are allowed to place orders for the variant when it's out of stock.

inventory-quantity

The number of items in stock for this variant. Applicable only when the value of inventory-management is set to shopify.

option1

Options are custom properties that a shopowner can use to define variants. This is the first of three available options.

option2

This is the second of three available options.

option3

This is the third of three available options.

position

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

price

The price of the variant.

requires-shipping

Specifies whether or not the customer needs to provide a shipping address when placing an order for this variant. This can take on one of two values:

true: Indicates that the customer must provide a shipping address.
false: Indicates that the customer does not have to provide a shipping address.

In the admin panel, this value is set using the Require a shipping address checkbox when editing the variant.

sku (optional)

The SKU — stock-keeping unit — of the variant.

taxable

Specifies whether or not tax should be charged for the variant. This can take one of two values:

true: Indicates that tax should be charged for this variant.
false: Indicates that tax should not be charged for this variant.

In the admin panel, this value is set using the Charge taxes checkbox when editing the variant.

title

The title of the variant. This is automatically generated from the variant's values for option1, option2 and option3.

updated-at

The date and time when the variant was last updated.

How to get a list of a product's variants

To get a list of variants for a given product, use a GET call to the product resource, as shown below:

GET https://api_key:shared_secret@hostname/admin/products/product_id/variants.format

where:

api_key is your app's API key,
shared_secret is your app's shared secret,
hostname is the shop's "myshopify.com" domain (e.g. thisismyshop.myshopify.com),
product_id is the product's id and
format is either json or xml.

You can use the fields input parameter (see below) to limit the number of properties returned with the order.

In this example, we want to retrieve the variants for the product whose id is 632910392.

JSON

The request:

GET https://api_key:shared_secret@hostname/admin/products/632910392/variants.json

The response:

HTTP/1.1 200 OK[]
 {
   "variants": [
     {
       "compare_at_price": null,
       "created_at": "2012-03-13T16:09:58-04:00",
       "fulfillment_service": "manual",
       "grams": 200,
       "id": 808950810,
       "inventory_management": "shopify",
       "inventory_policy": "continue",
       "option1": "Pink",
       "option2": null,
       "option3": null,
       "position": 1,
       "price": "199.00",
       "requires_shipping": true,
       "sku": "IPOD2008PINK",
       "taxable": true,
       "title": "Pink",
       "updated_at": "2012-03-13T16:09:58-04:00",
       "inventory_quantity": 10
     },
     {
       "compare_at_price": null,
       "created_at": "2012-03-13T16:09:58-04:00",
       "fulfillment_service": "manual",
       "grams": 200,
       "id": 49148385,
       "inventory_management": "shopify",
       "inventory_policy": "continue",
       "option1": "Red",
       "option2": null,
       "option3": null,
       "position": 2,
       "price": "199.00",
       "requires_shipping": true,
       "sku": "IPOD2008RED",
       "taxable": true,
       "title": "Red",
       "updated_at": "2012-03-13T16:09:58-04:00",
       "inventory_quantity": 20
     },
     {
       "compare_at_price": null,
       "created_at": "2012-03-13T16:09:58-04:00",
       "fulfillment_service": "manual",
       "grams": 200,
       "id": 39072856,
       "inventory_management": "shopify",
       "inventory_policy": "continue",
       "option1": "Green",
       "option2": null,
       "option3": null,
       "position": 3,
       "price": "199.00",
       "requires_shipping": true,
       "sku": "IPOD2008GREEN",
       "taxable": true,
       "title": "Green",
       "updated_at": "2012-03-13T16:09:58-04:00",
       "inventory_quantity": 30
     },
     {
       "compare_at_price": null,
       "created_at": "2012-03-13T16:09:58-04:00",
       "fulfillment_service": "manual",
       "grams": 200,
       "id": 457924702,
       "inventory_management": "shopify",
       "inventory_policy": "continue",
       "option1": "Black",
       "option2": null,
       "option3": null,
       "position": 4,
       "price": "199.00",
       "requires_shipping": true,
       "sku": "IPOD2008BLACK",
       "taxable": true,
       "title": "Black",
       "updated_at": "2012-03-13T16:09:58-04:00",
       "inventory_quantity": 40
     }
   ]
 }

XML

The request:

GET https://api_key:shared_secret@hostname/admin/products/632910392/variants.xml

The response:

HTTP/1.1 200 OK[]
 <?xml version="1.0" encoding="UTF-8"?>
 <variants type="array">
   <variant>
     <compare-at-price type="decimal" nil="true"></compare-at-price>
     <created-at type="datetime">2012-03-13T16:11:26-04:00</created-at>
     <fulfillment-service>manual</fulfillment-service>
     <grams type="integer">200</grams>
     <id type="integer">808950810</id>
     <inventory-management>shopify</inventory-management>
     <inventory-policy>continue</inventory-policy>
     <option1>Pink</option1>
     <option2 nil="true"></option2>
     <option3 nil="true"></option3>
     <position type="integer">1</position>
     <price type="decimal">199.0</price>
     <requires-shipping type="boolean">true</requires-shipping>
     <sku>IPOD2008PINK</sku>
     <taxable type="boolean">true</taxable>
     <title>Pink</title>
     <updated-at type="datetime">2012-03-13T16:11:26-04:00</updated-at>
     <inventory-quantity type="integer">10</inventory-quantity>
   </variant>
   <variant>
     <compare-at-price type="decimal" nil="true"></compare-at-price>
     <created-at type="datetime">2012-03-13T16:11:26-04:00</created-at>
     <fulfillment-service>manual</fulfillment-service>
     <grams type="integer">200</grams>
     <id type="integer">49148385</id>
     <inventory-management>shopify</inventory-management>
     <inventory-policy>continue</inventory-policy>
     <option1>Red</option1>
     <option2 nil="true"></option2>
     <option3 nil="true"></option3>
     <position type="integer">2</position>
     <price type="decimal">199.0</price>
     <requires-shipping type="boolean">true</requires-shipping>
     <sku>IPOD2008RED</sku>
     <taxable type="boolean">true</taxable>
     <title>Red</title>
     <updated-at type="datetime">2012-03-13T16:11:26-04:00</updated-at>
     <inventory-quantity type="integer">20</inventory-quantity>
   </variant>
   <variant>
     <compare-at-price type="decimal" nil="true"></compare-at-price>
     <created-at type="datetime">2012-03-13T16:11:26-04:00</created-at>
     <fulfillment-service>manual</fulfillment-service>
     <grams type="integer">200</grams>
     <id type="integer">39072856</id>
     <inventory-management>shopify</inventory-management>
     <inventory-policy>continue</inventory-policy>
     <option1>Green</option1>
     <option2 nil="true"></option2>
     <option3 nil="true"></option3>
     <position type="integer">3</position>
     <price type="decimal">199.0</price>
     <requires-shipping type="boolean">true</requires-shipping>
     <sku>IPOD2008GREEN</sku>
     <taxable type="boolean">true</taxable>
     <title>Green</title>
     <updated-at type="datetime">2012-03-13T16:11:26-04:00</updated-at>
     <inventory-quantity type="integer">30</inventory-quantity>
   </variant>
   <variant>
     <compare-at-price type="decimal" nil="true"></compare-at-price>
     <created-at type="datetime">2012-03-13T16:11:26-04:00</created-at>
     <fulfillment-service>manual</fulfillment-service>
     <grams type="integer">200</grams>
     <id type="integer">457924702</id>
     <inventory-management>shopify</inventory-management>
     <inventory-policy>continue</inventory-policy>
     <option1>Black</option1>
     <option2 nil="true"></option2>
     <option3 nil="true"></option3>
     <position type="integer">4</position>
     <price type="decimal">199.0</price>
     <requires-shipping type="boolean">true</requires-shipping>
     <sku>IPOD2008BLACK</sku>
     <taxable type="boolean">true</taxable>
     <title>Black</title>
     <updated-at type="datetime">2012-03-13T16:11:26-04:00</updated-at>
     <inventory-quantity type="integer">40</inventory-quantity>
   </variant>
 </variants>

How to get a single product variant

To get a single product variant for a given product, use a GET call to the product resource, as shown below:

GET https://api_key:shared_secret@hostname/admin/products/product_id/variants/product_variant_id.format

where:

api_key is your app's API key,
shared_secret is your app's shared secret,
hostname is the shop's "myshopify.com" domain (e.g. thisismyshop.myshopify.com),
product_id is the id of the product,
product_variant_id is the id of the product variant and
format is either json or xml.

You can use the fields input parameter (see below) to limit the number of properties returned with the order.

In this example, we want to retrieve the variant for the product whose id is 632910392; the product variant id is 808950810.

JSON

The request:

GET https://api_key:shared_secret@hostname/admin/products/632910392/variants/808950810.json

The response:

HTTP/1.1 200 OK[]
 {
   "variant": {
     "compare_at_price": null,
     "created_at": "2012-03-13T16:09:58-04:00",
     "fulfillment_service": "manual",
     "grams": 200,
     "id": 808950810,
     "inventory_management": "shopify",
     "inventory_policy": "continue",
     "option1": "Pink",
     "option2": null,
     "option3": null,
     "position": 1,
     "price": "199.00",
     "requires_shipping": true,
     "sku": "IPOD2008PINK",
     "taxable": true,
     "title": "Pink",
     "updated_at": "2012-03-13T16:09:58-04:00",
     "inventory_quantity": 10
   }
 }

XML

The request:

GET https://api_key:shared_secret@hostname/admin/products/632910392/images/808950810.xml

The response:

HTTP/1.1 200 OK[]
 <?xml version="1.0" encoding="UTF-8"?>
 <variant>
   <compare-at-price type="decimal" nil="true"></compare-at-price>
   <created-at type="datetime">2012-03-13T16:11:26-04:00</created-at>
   <fulfillment-service>manual</fulfillment-service>
   <grams type="integer">200</grams>
   <id type="integer">808950810</id>
   <inventory-management>shopify</inventory-management>
   <inventory-policy>continue</inventory-policy>
   <option1>Pink</option1>
   <option2 nil="true"></option2>
   <option3 nil="true"></option3>
   <position type="integer">1</position>
   <price type="decimal">199.0</price>
   <requires-shipping type="boolean">true</requires-shipping>
   <sku>IPOD2008PINK</sku>
   <taxable type="boolean">true</taxable>
   <title>Pink</title>
   <updated-at type="datetime">2012-03-13T16:11:26-04:00</updated-at>
   <inventory-quantity type="integer">10</inventory-quantity>
 </variant>

How to add a new product variant

To add a new variant to a product, use a POST call to the product resource, as shown below:

POST https://api_key:shared_secret@hostname/admin/products/product_id/variants.format

where:

api_key is your app's API key,
shared_secret is your app's shared secret,
hostname is the shop's "myshopify.com" domain (e.g. thisismyshop.myshopify.com),
product_id is the id of the product and
format is either json or xml.

To specify the properties of the variant you want to add, include them in the request body.

In the example below, we'll create a new variant for the product whose id is 632910392 with the following properties:

option1: Default
price: 1.00

JSON

The request:

POST https://api_key:shared_secret@hostname/admin/products/'632910392/variants.json

The request body:

{
   "variant": {
     "option1": "Default",
     "price": "1.00"
   }
 }

The response:

HTTP/1.1 201 Created[]
 {
   "variant": {
     "compare_at_price": null,
     "created_at": "2012-03-13T16:10:45-04:00",
     "fulfillment_service": "manual",
     "grams": 0,
     "id": 961411825,
     "inventory_management": null,
     "inventory_policy": "deny",
     "option1": "Default",
     "option2": null,
     "option3": null,
     "position": 5,
     "price": "1.00",
     "requires_shipping": true,
     "sku": "",
     "taxable": true,
     "title": "Default",
     "updated_at": "2012-03-13T16:10:45-04:00",
     "inventory_quantity": 1
   }
 }

XML

The request:

POST https://api_key:shared_secret@hostname/admin/products/'632910392/variants.xml

The request body:

<?xml version="1.0" encoding="UTF-8"?>
 <variant>
   <option1>Default</option1>
   <price>1.00</price>
 </variant>

The response:

HTTP/1.1 201 Created[]
 <?xml version="1.0" encoding="UTF-8"?>
 <variant>
   <compare-at-price type="decimal" nil="true"></compare-at-price>
   <created-at type="datetime">2012-03-13T16:12:12-04:00</created-at>
   <fulfillment-service>manual</fulfillment-service>
   <grams type="integer">0</grams>
   <id type="integer">961411843</id>
   <inventory-management nil="true"></inventory-management>
   <inventory-policy>deny</inventory-policy>
   <option1>Default</option1>
   <option2 nil="true"></option2>
   <option3 nil="true"></option3>
   <position type="integer">5</position>
   <price type="decimal">1.0</price>
   <requires-shipping type="boolean">true</requires-shipping>
   <sku></sku>
   <taxable type="boolean">true</taxable>
   <title>Default</title>
   <updated-at type="datetime">2012-03-13T16:12:12-04:00</updated-at>
   <inventory-quantity type="integer">1</inventory-quantity>
 </variant>

How to modify a product variant

To make changes to a variant, use a PUT call to the variant resource, as shown below:

PUT https://api_key:shared_secret@hostname/admin/variants/variant_id.format

where:

api_key is your app's API key,
shared_secret is your app's shared secret,
hostname is the shop's "myshopify.com" domain (e.g. thisismyshop.myshopify.com),
variant_id is the id of the variant and
format is either json or xml.

You'll also need to specify the properties you want to update in the body of the request, in either JSON or XML format (the format must be the same as the format specified in the POST call).

Updating the inventory count of a variant

In this example, we want to change the inventory count of the variant whose id is 808950810 to 100.

JSON

The request:

PUT https://api_key:shared_secret@hostname/admin/variants/808950810.json

The request body:

{
   "variant": {
     "id": 808950810,
     "inventory_quantity": 100
   }
 }

The response:

HTTP/1.1 200 OK[]
 {
   "variant": {
     "compare_at_price": null,
     "created_at": "2012-03-13T16:09:58-04:00",
     "fulfillment_service": "manual",
     "grams": 200,
     "id": 808950810,
     "inventory_management": "shopify",
     "inventory_policy": "continue",
     "option1": "Pink",
     "option2": null,
     "option3": null,
     "position": 1,
     "price": "199.00",
     "requires_shipping": true,
     "sku": "IPOD2008PINK",
     "taxable": true,
     "title": "Pink",
     "updated_at": "2012-03-13T16:10:45-04:00",
     "inventory_quantity": 100
   }
 }

XML

The request:

 PUT https://api_key:shared_secret@hostname/admin/variants/808950810.xml

The request body:

<?xml version="1.0" encoding="UTF-8"?>
 <variant>
   <id type="integer">808950810</id>
   <inventory-quantity type="integer">100</inventory-quantity>
 </variant>

The response:

HTTP/1.1 200 OK[]
 <?xml version="1.0" encoding="UTF-8"?>
 <variant>
   <compare-at-price type="decimal" nil="true"></compare-at-price>
   <created-at type="datetime">2012-03-13T16:11:26-04:00</created-at>
   <fulfillment-service>manual</fulfillment-service>
   <grams type="integer">200</grams>
   <id type="integer">808950810</id>
   <inventory-management>shopify</inventory-management>
   <inventory-policy>continue</inventory-policy>
   <option1>Pink</option1>
   <option2 nil="true"></option2>
   <option3 nil="true"></option3>
   <position type="integer">1</position>
   <price type="decimal">199.0</price>
   <requires-shipping type="boolean">true</requires-shipping>
   <sku>IPOD2008PINK</sku>
   <taxable type="boolean">true</taxable>
   <title>Pink</title>
   <updated-at type="datetime">2012-03-13T16:12:13-04:00</updated-at>
   <inventory-quantity type="integer">100</inventory-quantity>
 </variant>

How to delete a product variant

To delete a product variant, use a DELETE call to the product resource, as shown below:

DELETE https://api_key:shared_secret@hostname/admin/variants/product_variant_id.format

where:

api_key is your app's API key,
shared_secret is your app's shared secret,
hostname is the shop's "myshopify.com" domain (e.g. thisismyshop.myshopify.com),
product_variant_id is the id of the product variant and
format is either json or xml.

In this example, we want to delete the product variant whose id is 808950810.

JSON

The request:

DELETE https://api_key:shared_secret@hostname/admin/variants/808950810.json

The response:

HTTP/1.1 200 OK[]

XML

The request:

DELETE https://api_key:shared_secret@hostname/admin/variants/808950810.xml

The response:

HTTP/1.1 200 OK[]

Search

Using Shopify

Intro to Shopify

Misc.

Your shop's design

Using Shopify 2

Store content

Store Management

Store Settings

Theme Settings

Designing

Shopify 101

Tutorials

Resources

Developing

Developing resources

Tutorials

Wiki Administration

Navigation

Toolbox

Product Variant (API)

From Shopify Wiki

Contents

Variant properties

How to get a list of a product's variants

JSON

XML

How to get a single product variant

JSON

XML

How to add a new product variant

JSON

XML

How to modify a product variant

Updating the inventory count of a variant

JSON

XML

How to delete a product variant

JSON

XML