Variants can be accessed through the API via the variants base URL:

$ curl
  • Supported list methods: GET POST
  • Supported detail methods: GET PUT DELETE

A Variant is a specific variation on an Item, the most common examples of which are color & size. You can read more about Variants in the bulk import documentation.


variant.item (reference to Item)

The Item that this Variant is connected to. This cannot be null.

variant.sku (string)

The SKU or "product code" of the Variant. This must be unique within your account; you cannot have two Variants with the same sku.

variant.barcode (string)
variant.unitPrice (decimal)

The price for a single unit of this Variant. Unlike Items, this can be null, which means that the price of the Variant is assumed to be the same as the price of its item.

By default, this is the "base" unit price of the Variant, however, the pricesForCustomer query parameter (see below) can be used to cause a GET to return the pricing that is applicable to a particular Customer.

If pricesForCustomer is specified, then the value of this will never be null and will always return a real decimal value, even if that value is equal to the actual base unit price of the Item.

variant.dimensions (list of dictionaries)

A list of dictionaries, each of which represents a "dimension" of the Variant. Below is an example of the dimensions property representing a Size "2" / Color "Black" Variant:

    {"dimension": "Size", "value": "2"},
    {"dimension": "Color", "value": "Black"}

For Variants of more than one dimension, the order of the dictionaries in this list is important: it determines the order in which the dimensions are presented for choice in the app.


pricesForCustomer (integer)

If you pass pricesForCustomer=<objID> as a request parameter with the objID of a Customer, the unitPrice field in the results will return the pricing that is applicable to that customer, rather than the base unit price defined for the Variant.

This isn't so much a "filter" as a "modifier", since it does not change which Variants are returned in the response.


    "barcode": "167318831223", 
    "cdate": "2011-01-18", 
    "ctime": "2011-01-18T17:52:04Z", 
    "dimensions": [
            "dimension": "Color", 
            "value": "Blue"
            "dimension": "Size", 
            "value": "30"
    "entityType": "Variant", 
    "item": "/api/v2/items/974", 
    "mtime": "2011-12-22T22:11:31Z", 
    "objID": 93015, 
    "owner": "system", 
    "resource_uri": "/api/v2/variants/93015", 
    "sku": "M.JN.01.003", 
    "unitPrice": null, 
    "uuid": "0e4581c9-3a3b-4b51-af3b-544332001f40"
Next: Categories