Product Variations

Overview

Variations allow you to generate child products on a product based with a number of options. In the simple example below we have a size variation with three options (small, medium and large) and a color variation with three options (green, red and blue). This creates a variation matrix with 9 possible unique combinations or "child products".

It's possible to create many more variations and options than the simple example above. The limit is currently set to 250 possible unique combinations. Creating additional variations or options and attaching them to a product exponentially increases the number of unique combinations. For example, adding a third variation with three options to the example above would mean 3x3x3, a total of 27 unique child products would be created.

Re-usability

Variations are also re-usable, so you could attach the same variation to any number of products. In the example below we have a shoe size variation with 5 options. This variation has been linked to the two shoe products that should inherit this property. The T-shirt product is not linked to the Shoe Size variation. This means you won’t have to recreate a new size variation every time you add a new shoe, simply create a link between the existing variation and the new product.

Setup Summary

The process to use and set up variations on your product catalog is fairly linear. The diagram below highlights the first-time setup process we'll cover in this guide. In short, you will want a base product to have variations, options and modifiers defined. Then, simply link the product to the variation(s), and run the build endpoint to generate the variation matrix of child products.

Implementation Guide

Follow the steps below to create a product with several size and color variations.

1. Get your access token

You will need to get a client_credentials access token to follow along making the API requests outlined below.

curl -X "POST" "https://api.moltin.com/oauth/access_token" \
-d "client_id=XXXX" \
-d "client_secret=XXXX" \
-d "grant_type=client_credentials"

2. Create a product variation

A typical example of a product variation is product size. You could foresee needing a small, medium and large variation for a shirt.

cURL
Response
curl -X POST https://api.moltin.com/v2/variations \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $'{
"data": {
"type": "product-variation",
"name": "Shirt Size"
}
}'
{
"data": {
"type": "product-variation",
"id": "9c10417d-e2f8-4fad-9fca-5701c76576d9",
"name": "Shirt Size"
}
}

3. Create a product option

Product options are the actual variation options that you want to make available for your project. This is were you'll be able to outline the size you want to offer, i.e. small, medium or large.

Within our ecosystem, a variation is simply a container for a number of options.

cURL
Response
curl -X POST https://api.moltin.com/v2/variations/:variationId/options \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $'{
"data": {
"type": "option",
"name": "Small",
"description": "Size small"
}
}'
{
"data": {
"type": "product-variation",
"id": "ccfb0d2c-8ed5-4dd8-ab41-ba883f4d3fbb",
"name": "Shirt size",
"options": [
{
"id": "581dd431-38f0-415f-98fc-ec64b5aa7f9d",
"name": "small",
"description": "Size small",
"modifiers": []
},
{
"id": "f4413e4d-8258-4510-87f9-4af0d75bfcb1",
"name": "medium",
"description": "Size medium",
"modifiers": []
},
{
"id": "143814e1-c75f-46d4-8d14-97d15405321f",
"name": "large",
"description": "Size large",
"modifiers": []
}
],
"relationships": {
"options": {
"data":
{
"type": "option",
"id": "581dd431-38f0-415f-98fc-ec64b5aa7f9d"
}
}
}
}

Replace variationId with the ID that you generated for the particular variation, as shown above (step 2).

Repeat the step for every option you want to add. In the example above, we've added small, medium and large options (see the Response tab for details).

4. Create modifiers for your options

Modifiers determine how the child products built will vary from the base product. The minimum requirement is that each variation option MUST have both a SKU and a slug modifier(_append, _prepend, _equals). This is because these properties must be unique across your product rage.

cURL
Response
curl -X POST https://api.moltin.com/v2/variations/:variationId/options/:optionID/modifiers \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $'{
"data": {
"type": "modifier",
"modifier_type": "slug_append",
"value": "-small"
}
}
{
"data": {
"type": "product-variation",
"id": "ccfb0d2c-8ed5-4dd8-ab41-ba883f4d3fbb",
"name": "Shirt size",
"options": [
{
"id": "581dd431-38f0-415f-98fc-ec64b5aa7f9d",
"name": "small",
"description": "Size small",
"modifiers": [
{
"id": "d675108f-3c6e-4c03-bea0-eae03e009214",
"type": "slug_append",
"value": "-small"
},
{
"id": "48eadcae-dd11-4d40-be23-6e6404a43b3b",
"type": "sku_append",
"value": "-small"
}
]
},
{
"id": "f4413e4d-8258-4510-87f9-4af0d75bfcb1",
"name": "medium",
"description": "Size medium",
"modifiers": [
{
"id": "1118633c-c947-4f91-8b29-d055fac2d8b7",
"type": "slug_append",
"value": "-medium"
},
{
"id": "84b062ac-436d-4a20-8322-1319d39414b9",
"type": "sku_append",
"value": "-medium"
}
]
},
{
"id": "143814e1-c75f-46d4-8d14-97d15405321f",
"name": "large",
"description": "Size large",
"modifiers": [
{
"id": "b0e2f026-bb1f-4369-86a0-b4f3f367c2b6",
"type": "slug_append",
"value": "-large"
},
{
"id": "8eabf166-6617-4969-807e-72f4c5a64948",
"type": "sku_append",
"value": "-large"
}
]
}
],
"relationships": {
"options": {
"data": [
{
"type": "option",
"id": "581dd431-38f0-415f-98fc-ec64b5aa7f9d"
},
{
"type": "option",
"id": "f4413e4d-8258-4510-87f9-4af0d75bfcb1"
},
{
"type": "option",
"id": "143814e1-c75f-46d4-8d14-97d15405321f"
}
]
}
}
}
}

Repeat the step for every option you want to add a modifier to. In the example above, we've added small, medium and large options and slug and SKU modifiers (see the Response tab for details).

5. Create the Product Relationships

Now, we need to allocate the variations to the base product. In this example, this would be the shirt.

Repeat this for every product you wish to relate to this variation.

cURL
Response
curl -X POST \
https://api.moltin.com/v2/products/:productId/relationships/variations \
-H "Authorization: Bearer XXXX" \
-H 'content-type: application/json' \
-d '{
"data": [ {
"type": "product-variation",
"id": "{{variationId}}"
}]
}'
{
"type": "product",
"id": "d8e64f88-7bb4-4095-a7e8-a55d094648bb",
"name": "SPCA",
"slug": "shirt",
"sku": "1",
"manage_stock": false,
"description": "A shirt",
"price": [
{
"amount": 500,
"currency": "USD",
"includes_tax": true
}
],
"status": "live",
"commodity_type": "digital",
"meta": {
"timestamps": {
"created_at": "2018-05-03T19:36:31+00:00",
"updated_at": "2018-08-06T09:40:46+00:00"
},
"stock": {
"level": 0,
"availability": "out-stock"
},
"variations": {
"id": "ccfb0d2c-8ed5-4dd8-ab41-ba883f4d3fbb",
"name": "Shirt size",
"options": [
{
"id": "581dd431-38f0-415f-98fc-ec64b5aa7f9d",
"name": "small",
"description": "Size small"
},
{
"id": "f4413e4d-8258-4510-87f9-4af0d75bfcb1",
"name": "medium",
"description": "Size medium"
},
{
"id": "143814e1-c75f-46d4-8d14-97d15405321f",
"name": "large",
"description": "Size large"
}
]
}
]
},
"relationships": {
"variations": {
"data": [
{
"type": "product-variation",
"id": "0c02ca9f-27be-48a8-89d9-cd7c30699343"
}]
}
}
}
}

Replace productId with the ID of the base product.

Replace variationIdwith the ID for the variation you created (step 2).

6. Build Child Variations

Now that the variation is set up and it has products assigned to it, you'll need to trigger the process that will compile all of the variations and create the child variations.

cURL
Response
curl -X POST https://api.moltin.com/v2/products/:parentId/build/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer XXXX"
{
"data": [
{
"type": "product",
"id": "d74b43b5-e9bb-4bb9-99e8-4a8733316d8c",
"name": "SPCA",
"slug": "shirt-small",
"sku": "1-small",
"manage_stock": false,
"description": "A shirt",
"price": [
{
"currency": "USD",
"amount": 500,
"includes_tax": true
}
],
"status": "live",
"commodity_type": "digital"
},
{
"type": "product",
"id": "90f064ba-3a14-4bf8-afa7-336ccb991c49",
"name": "SPCA",
"slug": "shirt-medium",
"sku": "1-medium",
"manage_stock": false,
"description": "A shirt",
"price": [
{
"currency": "USD",
"amount": 500,
"includes_tax": true
}
],
"status": "live",
"commodity_type": "digital"
},
{
"type": "product",
"id": "bafd2ddc-7fab-4a60-ad2a-12fc6b99f8f6",
"name": "SPCA",
"slug": "shirt-large",
"sku": "1-large",
"manage_stock": false,
"description": "A shirt",
"price": [
{
"currency": "USD",
"amount": 500,
"includes_tax": true
}
],
"status": "live",
"commodity_type": "digital"
}
]
}

Replace parentId with the ID of the base product.

Child Variations in use

For adding a product defined by a variation to a cart or checking it out, make sure to use the child product ID, not the product ID. You can view your products variation relationships within the product object.

cURL
Response
curl -X GET https://api.moltin.com/v2/products/:id \
-H "Authorization: Bearer XXXX" \
{
"type": "product",
"id": "e6808653-a328-427c-9fcf-c4e0093cbd10",
"name": "Deck Shoe",
"slug": "deck-shoe_74",
"sku": "deck-shoe_74",
"manage_stock": false,
"description": "Modern boat shoes were invented in 1935 by American Paul A. Sperry",
"price": [
{
"amount": 5891,
"currency": "USD",
"includes_tax": true
}
],
"status": "live",
"commodity_type": "physical",
"meta": {
"timestamps": {
"created_at": "2018-07-23T15:29:41+00:00",
"updated_at": "2018-07-23T15:29:41+00:00"
},
"stock": {
"level": 0,
"availability": "out-stock"
}
},
"relationships": {
"parent": {
"data": {
"type": "product",
"id": "23230da6-5c0e-473e-b4aa-9ff76228df4b"
}
}
}
}

Rebuilding Child Products

You can hit the product/build endpoint at any time, whether you already generated child products or not. It will perform a rebuild of your child products for you.

If you have not updated any variations, options or modifiers, the resulting child products will be exactly the same as before.

If you have updated any variations, options or modifiers, then your old child products will be replaced with new ones based on the alterations made.