API Variation

From Spiffy Stores Knowledge Base

The Spiffy Stores API Variation object represents a product variation. A variation usually represents some physical version of a product that needs to be represented separately from other variations. Each product variation can have its inventory tracked separately.

You can view a product's variations, update them, create new ones, and delete them.

Accessing a Product

If you want to refer to a single Product then you will need to use the unique id that has been assigned to that object.

The object ids are internally generated by the software and cannot be created or assigned.

Alternatively, you may specify the object handle in place of the object id when requesting access to the object. The handle is the unique character string that is assigned to every product when it is created. The handle is used in the URL to display the product page.

For example, you may retrieve a product's variations in two ways. 

GET /api/products/12345678/variations.json

or

GET /api/products/cute-dog/variations.json

The advantage of using the handle form of the request is that you don't need to search all the products first in order to determine the product id, as you will already know what the handle is. This will reduce the number of API calls that you need to make and greatly simplifies the amount of coding that is needed to manage your products.

Variation Properties

id { "id" : 12345 }

A unique numeric identifier for the variation.

product_id { "product_id" : 123456789 }

The unique numeric identifier for the product of this variation.

title { "title" : "Red/Wool/Small" }

The title of the product variation.

position { "position" : 1 }

The position of the variation in the list of all product variantions. Position number 1 is at the top of the list.

option1 { "option1" : "Red" }

A product can have up to 3 options. Each variation will have a unique combination of option values. This is the value of option 1.

option2 { "option2" : "Wool" }

A product can have up to 3 options. Each variation will have a unique combination of option values. This is the value of option 2.

option3 { "option3" : "Small" }

A product can have up to 3 options. Each variation will have a unique combination of option values. This is the value of option 3.

sku { "sku" : "P123456REDWS" }

A unique identifier for the product variation, normally used for stock tracking purposes.

location_code { "location_code" : "ROW23BIN12" }

A code which represents the physical location of the item. The code is used to sort the packing list so that items are listed by physical location to make order picking easier.

barcode { "barcode" : "1234567809" }

The barcode, which is usually the UPC or ISBN number for the product variation.

price { "price" : 49.95 }

The price of the product variation.

wholesale_price { "wholesale_price" : 29.95 }

The wholesale price of the product variation. This price is used whenever a customer with the wholesale attribute logs in to the store.

compare_at_price { "compare_at_price" : 69.95 }

This price is used to show the regular price of a variation to highlight how much is being saved.

discount { "discount" : 5.00 }

This is the amount that this variation can have as a discount when it is eligible for a shopping cart discount. This amount overrides any general discount calculation for the cart.

taxable { "taxable" : true }

Indicates whether the product variation is subject to tax. Some items, such as food or books may be exempt from taxes such as GST or VAT.

instalments { "instalments" : 1 }

If instalments are enabled for this product, then this indicates the number of instalments that must be paid for this variation.

grams { "grams" : 200 }

The weight of the product variation in grams.

length { "length" : 100 }

The length of the product variation in cms.

width { "width" : 50 }

The width of the product variation in cms.

height { "height" : 20 }

The height of the product variation in cms.

inventory_quantity { "inventory_quantity" : 10 }

The number of items in stock for this product variation.

old_inventory_quantity { "old_inventory_quantity" : 10 }

The original number of items in stock for this product variation. This value must be provided when attempting to update the inventory quantity. If the old_inventory_quantity no longer matches the actual inventory quantity because the value has been updated elsewhere, then the attempt to update the quantity will fail and should be retried.

inventory_quantity_adjustment { "inventory_quantity_adjustment" : 5 }

If it is not important to determine the exact level of the inventory quantity, then an adjustment can be used instead to increment or decrement the inventory quantity by a certain amount.

inventory_management { "inventory_management" : "spiffy" }

Specifies whether or not Spiffy Stores tracks the number of items in stock for this product variation. Valid values are:

  • blank: Inventory for this product variation is not tracked.
  • spiffy: Inventory tracking is enabled for this product variation.
inventory_policy { "inventory_policy" : "continue" }

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

  • deny (default): Customers are not allowed to place orders for a product variation when it's out of stock.
  • continue: Customers are allowed to place orders for a product variation when it's out of stock.
  • archive: The product is hidden when the variation is out of stock, and customers are not allowed to place orders for the variation.
fulfilment_service { "fulfilment_service" : "manual" }

If orders are fulfilled by the store itself, then this is 'manual'. Otherwise the value is set to the fulfilment service that has been enabled for this product variation.

shipping_code { "shipping_code" : "BULK_ITEM" }

If a special shipping rate is required for this product variation, it is specified by the 'shipping_code'. This shipping rate overrides the default shipping rate for the destination.

free_shipping { "free_shipping" : false }

Indicates that this product variation is eligible for free shipping.

requires_shipping { "requires_shipping" : true }

Indicates that this product variation is a physical object that requires shipping.

ship_separately { "ship_separately" : false }

Indicates that the item is bulky and cannot be added to the total cart weight for the shipping rate calculation. The item is assessed for shipping as an individual parcel, based on its weight and dimensions which are required for separate shipping.

created_at { "created_at" : "2007-10-24T18:26:31Z" }

The date and time when the product variation was created. The timestamp is in ISO 8601 format.

updated_at { "updated_at" : "2014-01-16T05:50:56Z" }

The date and time when the product variation was last updated. The timestamp is in ISO 8601 format.

image_id { "image_id" : "123456789" }

The unique identifier of the image that is associated with this variation.

Endpoints

GET /api/products/(OBJECT_ID|OBJECT_HANDLE)/variations.json

Return a list of variations belonging to a product.

GET /api/variations.json

Return a list of variations belonging to a store.

Optional Parameters

limit Number of results returned. The default is 30, with a maximum of 50 in a single request.
page The number of the page to return. The number of results per page is set by the limit parameter. If more results are required, then submit the request again, increasing the page number each time.
ids A comma-separated list of variation ids.
since_id Limit the results to only include objects which have an id greater than the given value.
created_at_min Return only the product variations created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the product variations created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min Return only the product variations updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max Return only the product variations updated before the given date and time. Use the format "2014-12-31 12:00".
fields A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/products/123456789/variations.json

HTTP/1.1 200 OK

{
  "variations" : [
    {
      "id": 3139,
      "product_id": 123456789,
      "title": "Red/Wool",
      "position": 1,
      "sku": "123AAA",
      "location_code": "ROW12BIN3",
      "barcode": "",
      "price": "10.0",
      "wholesale_price": "0.0",
      "compare_at_price": "0.0",
      "discount": "0.0",
      "taxable": true,
      "instalments": 1,
      "grams": 500.0,
      "length": 0.0,
      "width": 0.0,
      "height": 0.0,
      "inventory_quantity": 50,
      "old_inventory_quantity": 50,
      "inventory_policy": "deny",
      "inventory_management": "spiffy",
      "fulfilment_service": "manual",
      "shipping_code": "",
      "free_shipping": false,
      "requires_shipping": true,
      "ship_separately": false,
      "created_at": "2014-11-20T23:10:50Z",
      "updated_at": "2014-11-20T23:10:51Z",
      "option1": "Red",
      "option2": "Wool"
    }, 
    {
      ...
    }
  ]   
}

GET /api/variations.json?fields=product_id,inventory_quantity&updated_at_min=2014-11-01 12:00

HTTP/1.1 200 OK

{
  "variations" : [
    { "product_id" : 1929, "inventory_quantity" : 0 },
    { "product_id" : 1930, "inventory_quantity" : 0 },
    { "product_id" : 1504, "inventory_quantity" : 101 },
    { "product_id" : 1504, "inventory_quantity" : 0 }
  ]
}

Examples using filters

GET /api/products/123456789/variations.json?fields=id,title

Alternative form

GET /api/products/fluffy-puppy/variations.json

GET /api/products/(OBJECT_ID|OBJECT_HANDLE)/variations/count.json

Return a count of product variations.

GET /api/variations/count.json

Return a count of variations belonging to a store.

Optional Parameters

since_id Limit the results to only include objects which have an id greater than the given value.
created_at_min Return only the product variations created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the product variations created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min Return only the product variations updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max Return only the product variations updated before the given date and time. Use the format "2014-12-31 12:00".

Example Request and Response

GET /api/products/fluffy-puppy/variations/count.json

HTTP/1.1 200 OK

{
  "count": 2
}

GET /api/variations/count.json

HTTP/1.1 200 OK

{
  "count": 115
}

Examples using filters

GET /api/products/123456789/variations/count.json?since_id=1000

GET /api/products/(OBJECT_ID|OBJECT_HANDLE)/variations/VARIATION_ID.json

Return a single product variation.

GET /api/variations/VARIATION_ID.json

Return a single product variation.

Optional Parameters

fields A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/products/123456789/variations/87675.json

HTTP/1.1 200 OK

{
  "variation": {
    "id": 3139,
    "product_id": 123456789,
    "title": "Red/Silk",
    "position": 1,
    "sku": "123AAA",
    "location_code": "ROW12BIN3",
    "barcode": "",
    "price": "10.0",
    "wholesale_price": "0.0",
    "compare_at_price": "0.0",
    "discount": "0.0",
    "taxable": true,
    "instalments": 1,
    "grams": 500.0,
    "length": 0.0,
    "width": 0.0,
    "height": 0.0,
    "inventory_quantity": 50,
    "old_inventory_quantity": 50,
    "inventory_policy": "deny",
    "inventory_management": "spiffy",
    "fulfilment_service": "manual",
    "shipping_code": "",
    "free_shipping": false,
    "requires_shipping": true,
    "ship_separately": false,
    "created_at": "2014-11-20T23:10:50Z",
    "updated_at": "2014-11-20T23:10:51Z",
    "option1": "Red",
    "option2": "Silk"
  }
}

Alternative forms

GET /api/products/cute-puppy/variations/87675.json
GET /api/variations/87675.json

POST /api/products/(OBJECT_ID|OBJECT_HANDLE)/variations.json

Create a new product variation.

Example Request and Response

POST /api/products/fluffy-puppy/variations.json

{
  "variation": {
    "option1": "Default Title",
    "price": "10.00",
    "sku" => "222222",
    "inventory_quantity" => 50
  }
}

HTTP/1.1 201 Created

PUT /api/products/(OBJECT_ID|OBJECT_HANDLE)/variations/VARIATION_ID.json

Update a product variation.

PUT /api/variations/VARIATION_ID.json

Update a product variation.

When you update a product variation, you must include the id parameter, which must match the variation_id specified in the POST URL.

When you update a product variation using the second form, you must include the product_id parameter, which must match the id of the product for the variation.

Example Request and Response

PUT /api/products/123456789/variations/45678.json

{
  "variation": {
    "id": 45678,
    "option1": "Blue",
    "price": "109.00"
  }
}

HTTP/1.1 200 OK

PUT /api/products/123456789/variations/45678.json

{
  "variation": {
    "id": 45678,
    "inventory_quantity": 100,
    "old_inventory_quantity": 10
  }
}

HTTP/1.1 200 OK

PUT /api/products/123456789/variations/45678.json

{
  "variation": {
    "id": 45678,
    "inventory_quantity_adjustment": -10
  }
}

HTTP/1.1 200 OK

DELETE /api/products/(OBJECT_ID|OBJECT_HANDLE)/variations/VARIATION_ID.json

Delete a product variation.

Example Request and Response

DELETE /api/products/123456789/variations/45678.json

HTTP/1.1 200 OK

{}

Alternative form

DELETE /api/products/cute-puppy/variations/45678.json





Further Reference

Retrieved from "http://www.spiffystores.com.au/kb/index.php?title=API_Variation&oldid=8091"