• Log in
  • Contact Us

Get in touch  

Developer Guides • Products

Working with the Product Variations API

Last updated: 24 Jun 2019

Product variations allow you to generate child products on a product parent with a number of options.


  • Moltin account (you'll need Client ID and Client Secret of your store).
  • Decent understanding of object-oriented programming or JavaScript.

Summary of steps required

  • Create a Product
  • Create a Product variation, e.g. product size
  • Create Product options, e.g. small, medium, large
  • Create modifiers for your option to determine how the child products will vary from the base product
  • Create Product relationships to link the variations with the base product
  • Compile all variations and create the child variations

Step-by-step walkthrough

In this scenario we will build a product size variation with small, medium and large size options.

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 -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"

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 -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"

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.

For more details, see: Modifiers.

Repeat the step for every option you want to add a modifier to.

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"

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 -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": "VARIATION-ID"
  • 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.

Replace parentId with the ID of the base product.

curl -X POST https://api.moltin.com/v2/products/:parentId/build/ \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer XXXX"

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 -X GET https://api.moltin.com/v2/products/:id \
     -H "Authorization: Bearer XXXX" \

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.

Further reading

Explore More Developer Guides

26 Jun 2019

Manage abandoned carts with Flows

Quick intro on how carts work There are three aspects of how Moltin carts operate:

Read More
Matt Foyle
in Flows | Carts
14 Jun 2019

Extend the order and cart resource with Flows

Extend the order resource to add shipping provider and a consignment number.

Read More
Joanna Suau
in Flows | Orders | Carts
14 Jun 2019

Store data form third party integration with Flows

Store nexus locations from a tax calculation service using Flows.

Read More
Joanna Suau
in Flows | Integrations