Product Variant

A product variant is a different version of a product, such as differing sizes or differing colours.

#

Without product variants, you would have to treat the small, medium and large versions of a t-shirt as three separate products; product variants let you treat the small, medium and large versions of a t-shirt as variations of the same product.

Each product can have a maximum of 100 variants.

What can you do with Product Variant?

The haravan 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" : "null" }

The competitors prices for the same item.

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

The date and time when the product variant was created. The API returns this value in ISO 8601 format.

fulfillment_service
{ "fulfillment_service" : "manual" }

Service who is doing the fulfillment. Valid values are: manual,

grams
{ "grams" : 200 }

The weight of the product variant in grams.

id
{ "id" : 808950810 }

The unique numeric identifier for the product variant.

inventory_management
{ "inventory_management" : "haravan" }

Specifies whether or not haravan tracks the number of items in stock for this product variant. Valid values are:

  • blank: haravan does not track the number of items in stock for this product variant.
  • haravan: haravan does track the number of items in stock for this product variant.


inventory_policy
{ "inventory_policy" : "continue" }

Specifies whether or not customers are allowed to place an order for a product variant when it's out of stock. Valid values are:

  • deny (default): Customers are not allowed to place orders for a product variant when it's out of stock.
  • continue: Customers are allowed to place orders for a product variatn when it's out of stock.


inventory_quantity
{ "inventory_quantity" : "10" }

The number of items in stock for this product variant.

old_inventory_quantity
{ "old_inventory_quantity" : "5" }

The original stock level the client believes the product variant has. This should be sent to avoid a race condition when the item being adjusted is simultaneously sold online.

inventory_quantity_adjustment
{ "inventory_quantity_adjustment" : "5" }

Instead of sending a new and old value for inventory an adjustment value can be sent. If an adjustment value is sent it will take priority.

metafield
{ "key" : "new" }
{ "value" : "newvalue" }
{ "value_type" : "string" }
{ "namespace" : "global" }


Attaches additional information to a shop's resources.

  • key (required): Identifier for the metafield (maximum of 30 characters).
  • namespace (required): Container for a set of metadata. Namespaces help distinguish between metadata you created and metadata created by another individual with a similar namespace (maximum of 20 characters).
  • value (required): Information to be stored as metadata.
  • value_type (required): States whether the information in the value is stored as a 'string' or 'integer.'
  • description (optional): Additional information about the metafield.


option
{ "option1" : "Pink" }

Custom properties that a shop owner can use to define product variants. Multiple options can exist. Options are represented as: option1, option2, option3 etc.

position
{ "position" : "1" }

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

price
{ "price" : 199.0 }

The price of the product variant.

product_id
{ "product_id" : 632910392 }

The unique numeric identifier for the product.

requires_shipping
{ "requires_shipping" : true }

Specifies whether or not a customer needs to provide a shipping address when placing an order for this product variant. Valid values are:

  • true: Customer needs to supply a shipping address.
  • false: Customer does not need to supply a shipping address.


sku
{ "sku" : "IPOD2008PINK" }

A unique identifier for the product in the shop.

taxable
{ "taxable" : true }

Specifies whether or not a tax is charged when the product variant is sole.

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. The API returns this value 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 system that the product variant's weight is measure in. The weight_unit can be either "g", "kg, "oz", or "lb".

image_id
{ "image_id" : 434522 }

The unique numeric identifier for one of the product's images.

Endpoints

GET/admin/products/632910392/variants.json

Get a list of product variants

limit

Amount of results

(default: 50) (maximum: 250)
page

Page to show

(default: 1)
since_id

Restrict results to after the specified ID

fields

comma-separated list of fields to include in the response

Get all variants for a product

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

Get all variants for a product after a specified ID

GET /admin/products/#{id}/variants.json?since_id=49148385
View Response
HTTP/1.1 200 OK
{
  "variants": [
    {
      "barcode": "1234_black",
      "compare_at_price": null,
      "created_at": "2015-03-28T13:31:19-04:00",
      "fulfillment_service": "manual",
      "grams": 200,
      "id": 457924702,
      "inventory_management": "haravan",
      "inventory_policy": "continue",
      "option1": "Black",
      "option2": null,
      "option3": null,
      "position": 4,
      "price": "199.00",
      "product_id": 632910392,
      "requires_shipping": true,
      "sku": "IPOD2008BLACK",
      "taxable": true,
      "title": "Black",
      "updated_at": "2015-03-28T13:31:19-04:00",
      "inventory_quantity": 40,
      "old_inventory_quantity": 40,
      "image_id": null,
      "weight": 0.2,
      "weight_unit": "kg"
    },
    {
      "barcode": "1234_pink",
      "compare_at_price": null,
      "created_at": "2015-03-28T13:31:19-04:00",
      "fulfillment_service": "manual",
      "grams": 200,
      "id": 808950810,
      "inventory_management": "haravan",
      "inventory_policy": "continue",
      "option1": "Pink",
      "option2": null,
      "option3": null,
      "position": 1,
      "price": "199.00",
      "product_id": 632910392,
      "requires_shipping": true,
      "sku": "IPOD2008PINK",
      "taxable": true,
      "title": "Pink",
      "updated_at": "2015-03-28T13:31:19-04:00",
      "inventory_quantity": 10,
      "old_inventory_quantity": 10,
      "image_id": 562641783,
      "weight": 0.2,
      "weight_unit": "kg"
    }
  ]
}
GET/admin/products/632910392/variants/count.json

Get a count of product variants


Count all variants for a product

GET /admin/products/#{id}/variants/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 4
}
GET/admin/variants/808950810.json

Get a single product variant by id

fields

comma-separated list of fields to include in the response

Get a product variant by id

GET /admin/variants/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "variant": {
    "barcode": "1234_pink",
    "compare_at_price": null,
    "created_at": "2015-03-28T13:31:19-04:00",
    "fulfillment_service": "manual",
    "grams": 200,
    "id": 808950810,
    "inventory_management": "haravan",
    "inventory_policy": "continue",
    "option1": "Pink",
    "option2": null,
    "option3": null,
    "position": 1,
    "price": "199.00",
    "product_id": 632910392,
    "requires_shipping": true,
    "sku": "IPOD2008PINK",
    "taxable": true,
    "title": "Pink",
    "updated_at": "2015-03-28T13:31:19-04:00",
    "inventory_quantity": 10,
    "old_inventory_quantity": 10,
    "image_id": 562641783,
    "weight": 0.2,
    "weight_unit": "kg"
  }
}
POST/admin/products/632910392/variants.json

Create a new product variant


Create a new product variant

POST /admin/products/#{id}/variants.json
{
  "variant": {
    "option1": "Default Title",
    "price": "1.00"
  }
}
View Response
HTTP/1.1 201 Created
{
  "variant": {
    "barcode": null,
    "compare_at_price": null,
    "created_at": "2015-03-28T13:32:38-04:00",
    "fulfillment_service": "manual",
    "grams": 0,
    "id": 1044399249,
    "inventory_management": null,
    "inventory_policy": "deny",
    "option1": "Default Title",
    "option2": null,
    "option3": null,
    "position": 5,
    "price": "1.00",
    "product_id": 632910392,
    "requires_shipping": true,
    "sku": "",
    "taxable": true,
    "title": "Default Title",
    "updated_at": "2015-03-28T13:32:38-04:00",
    "inventory_quantity": 1,
    "old_inventory_quantity": 1,
    "image_id": null,
    "weight": 0.0,
    "weight_unit": "kg"
  }
}

Create a new product variant with a metafield

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

Create a new product variant with an image

POST /admin/products/#{id}/variants.json
{
  "variant": {
    "image_id": 850703190
  }
}
View Response
HTTP/1.1 201 Created
{
  "variant": {
    "barcode": null,
    "compare_at_price": null,
    "created_at": "2015-03-28T13:32:39-04:00",
    "fulfillment_service": "manual",
    "grams": 0,
    "id": 1044399251,
    "inventory_management": null,
    "inventory_policy": "deny",
    "option1": "Default Title",
    "option2": null,
    "option3": null,
    "position": 5,
    "price": "0.00",
    "product_id": 632910392,
    "requires_shipping": true,
    "sku": "",
    "taxable": true,
    "title": "Default Title",
    "updated_at": "2015-03-28T13:32:39-04:00",
    "inventory_quantity": 1,
    "old_inventory_quantity": 1,
    "image_id": 850703190,
    "weight": 0.0,
    "weight_unit": "kg"
  }
}
PUT/admin/variants/808950810.json

Update an existing product variant


Add a metafield to an existing variant

PUT /admin/variants/#{id}.json
{
  "variant": {
    "id": 808950810,
    "metafields": [
      {
        "key": "new",
        "value": "newvalue",
        "value_type": "string",
        "namespace": "global"
      }
    ]
  }
}
View Response
HTTP/1.1 200 OK
{
  "variant": {
    "barcode": "1234_pink",
    "compare_at_price": null,
    "created_at": "2015-03-28T13:31:19-04:00",
    "fulfillment_service": "manual",
    "grams": 200,
    "id": 808950810,
    "inventory_management": "haravan",
    "inventory_policy": "continue",
    "option1": "Pink",
    "option2": null,
    "option3": null,
    "position": 1,
    "price": "199.00",
    "product_id": 632910392,
    "requires_shipping": true,
    "sku": "IPOD2008PINK",
    "taxable": true,
    "title": "Pink",
    "updated_at": "2015-03-28T13:31:19-04:00",
    "inventory_quantity": 10,
    "old_inventory_quantity": 10,
    "image_id": 562641783,
    "weight": 0.2,
    "weight_unit": "kg"
  }
}

Add an existing image to an existing variant

PUT /admin/variants/#{id}.json
{
  "variant": {
    "id": 808950810,
    "image_id": 562641783
  }
}
View Response
HTTP/1.1 200 OK
{
  "variant": {
    "barcode": "1234_pink",
    "compare_at_price": null,
    "created_at": "2015-03-28T13:31:19-04:00",
    "fulfillment_service": "manual",
    "grams": 200,
    "id": 808950810,
    "inventory_management": "haravan",
    "inventory_policy": "continue",
    "option1": "Pink",
    "option2": null,
    "option3": null,
    "position": 1,
    "price": "199.00",
    "product_id": 632910392,
    "requires_shipping": true,
    "sku": "IPOD2008PINK",
    "taxable": true,
    "title": "Pink",
    "updated_at": "2015-03-28T13:32:41-04:00",
    "inventory_quantity": 10,
    "old_inventory_quantity": 10,
    "image_id": 562641783,
    "weight": 0.2,
    "weight_unit": "kg"
  }
}

Update the title and price of an existing variant

PUT /admin/variants/#{id}.json
{
  "variant": {
    "id": 808950810,
    "option1": "Not Pink",
    "price": "99.00"
  }
}
View Response
HTTP/1.1 200 OK
{
  "variant": {
    "barcode": "1234_pink",
    "compare_at_price": null,
    "created_at": "2015-03-28T13:31:19-04:00",
    "fulfillment_service": "manual",
    "grams": 200,
    "id": 808950810,
    "inventory_management": "haravan",
    "inventory_policy": "continue",
    "option1": "Not Pink",
    "option2": null,
    "option3": null,
    "position": 1,
    "price": "99.00",
    "product_id": 632910392,
    "requires_shipping": true,
    "sku": "IPOD2008PINK",
    "taxable": true,
    "title": "Not Pink",
    "updated_at": "2015-03-28T13:32:41-04:00",
    "inventory_quantity": 10,
    "old_inventory_quantity": 10,
    "image_id": 562641783,
    "weight": 0.2,
    "weight_unit": "kg"
  }
}

Update a variant's inventory using an adjustment

PUT /admin/variants/#{id}.json
{
  "variant": {
    "id": 808950810,
    "inventory_quantity_adjustment": -5
  }
}
View Response
HTTP/1.1 200 OK
{
  "variant": {
    "barcode": "1234_pink",
    "compare_at_price": null,
    "created_at": "2015-03-28T13:31:19-04:00",
    "fulfillment_service": "manual",
    "grams": 200,
    "id": 808950810,
    "inventory_management": "haravan",
    "inventory_policy": "continue",
    "option1": "Pink",
    "option2": null,
    "option3": null,
    "position": 1,
    "price": "199.00",
    "product_id": 632910392,
    "requires_shipping": true,
    "sku": "IPOD2008PINK",
    "taxable": true,
    "title": "Pink",
    "updated_at": "2015-03-28T13:32:41-04:00",
    "inventory_quantity": 5,
    "old_inventory_quantity": 5,
    "image_id": 562641783,
    "weight": 0.2,
    "weight_unit": "kg"
  }
}

Update a variant's inventory

PUT /admin/variants/#{id}.json
{
  "variant": {
    "id": 808950810,
    "inventory_quantity": 100,
    "old_inventory_quantity": 10
  }
}
View Response
HTTP/1.1 200 OK
{
  "variant": {
    "barcode": "1234_pink",
    "compare_at_price": null,
    "created_at": "2015-03-28T13:31:19-04:00",
    "fulfillment_service": "manual",
    "grams": 200,
    "id": 808950810,
    "inventory_management": "haravan",
    "inventory_policy": "continue",
    "option1": "Pink",
    "option2": null,
    "option3": null,
    "position": 1,
    "price": "199.00",
    "product_id": 632910392,
    "requires_shipping": true,
    "sku": "IPOD2008PINK",
    "taxable": true,
    "title": "Pink",
    "updated_at": "2015-03-28T13:32:41-04:00",
    "inventory_quantity": 100,
    "old_inventory_quantity": 100,
    "image_id": 562641783,
    "weight": 0.2,
    "weight_unit": "kg"
  }
}
DELETE/admin/products/632910392/variants/808950810.json

Delete a product variant

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