Creating Variants

1. Create main/parent product

All the usual required data (name, sku, handle and retail_price) needs to be posted along with at least one set of variant options. It can be done by sending a POST request with the following payload to:

http://{domain_prefix}.vendhq.com/api/products

Request payload:

{
    "name": "API Variant",
    "sku": "api_variant_sku",
    "handle": "api_variant_handle",
    "retail_price": 123.45678,
    "variant_option_one_name": "sample_color",
    "variant_option_one_value": "yellow"
}

WARNING: Do not include button_order as this may cause nested variants. The order of variants shown in the product page UI will be based on the order the variants are created by default. Since the user has the ability to change this order directly, excluding this on creation and updates is the safest approach.

Response payload:

{
    "product": {
        "id": "06bf537b-c783-11e6-f6b9-85d5ab5a0c45",
        "source_id": "",
        "variant_source_id": "",
        "handle": "api_variant_handle",
        "type": "",
        "has_variants": true,
        "variant_parent_id": "",
        "variant_option_one_name": "",
        "variant_option_one_value": "yellow",
        "variant_option_two_name": "",
        "variant_option_two_value": "",
        "variant_option_three_name": "",
        "variant_option_three_value": "",
        "active": true,
        "name": "API Variant / yellow",
        "base_name": "API Variant",
        ...
    }
}

NOTE: You can see above that the variant_option_one_name value appears as blank, even though it was submitted in the payload. That is because variant options are only active for variant products and our product doesn't really have any variant children yet. Don't worry, we'll create them in a second.

2. Create the first variant

In order to do that, we'll need to post a very similar payload as for the main product. There are 2 things that we have to change, the sku and the variant option value. The important thing to make sure of here is that the handle has to be exactly the same as the one of the parent product.

Request payload:

{
    "name": "API Variant",
    "sku": "api_variant_sku_1",
    "handle": "api_variant_handle",
    "retail_price": 123.45678,
    "variant_option_one_name": "sample_color",
    "variant_option_one_value": "orange"
}

Response payload:

{
    "product": {
        "id": "06bf537b-c783-11e6-f6b9-85d842b2f7a5",
        "source_id": "",
        "variant_source_id": "",
        "handle": "api_variant_handle",
        "type": "",
        "has_variants": false,
        "variant_parent_id": "06bf537b-c783-11e6-f6b9-85d5ab5a0c45",
        "variant_option_one_name": "",
        "variant_option_one_value": "orange",
        "variant_option_two_name": "",
        "variant_option_two_value": "",
        "variant_option_three_name": "",
        "variant_option_three_value": "",
        "active": true,
        "name": "API Variant / orange",
        "base_name": "API Variant",
        ...
    }
}

3. Create another variant

Let's just create another variant to have some more data to present.

Request payload:

{
      "name": "API Variant",
      "sku": "api_variant_sku_2",
      "handle": "api_variant_handle",
      "retail_price": 123.45678,
      "variant_option_one_name": "sample_color",
      "variant_option_one_value": "red"
}

Response payload:

{
    "product": {
        "id": "06bf537b-c783-11e6-f6b9-85d80bdc36c0",
        "source_id": "",
        "variant_source_id": "",
        "handle": "api_variant_handle",
        "type": "",
        "has_variants": false,
        "variant_parent_id": "06bf537b-c783-11e6-f6b9-85d5ab5a0c45",
        "variant_option_one_name": "",
        "variant_option_one_value": "red",
        "variant_option_two_name": "",
        "variant_option_two_value": "",
        "variant_option_three_name": "",
        "variant_option_three_value": "",
        "active": true,
        "name": "API Variant / red",
        "base_name": "API Variant",
        ...
    }
}

4. Take a look at the parent product

We can do that by making a GET request to:

http://{domain_prefix}.vendhq.com/api/products

Response payload:

{
    "products": [
        {
            "id": "06bf537b-c783-11e6-f6b9-85d5ab5a0c45",
            "source_id": "",
            "variant_source_id": "",
            "handle": "api_variant_handle",
            "type": "",
            "has_variants": true,
            "variant_parent_id": "",
            "variant_option_one_name": "sample_color",
            "variant_option_one_value": "yellow",
            "variant_option_two_name": "",
            "variant_option_two_value": "",
            "variant_option_three_name": "",
            "variant_option_three_value": "",
            "active": true,
            "name": "API Variant / yellow",
            "base_name": "API Variant",
            ...
        }
    ]
}

Because this product finally has valid variants, the variant_option_one_name is returned with its value.

5. Get all the variants

Using the handle query parameter we can retrieve all the products with a given handle, which effectively means all the variants (parent and children) of that product:

https://{domain_prefix}.vendhq.com/api/products?handle={api_variant_handle}

Response payload:

{
    "products": [
        {
            "id": "06bf537b-c783-11e6-f6b9-85d5ab5a0c45",
            "source_id": "",
            "variant_source_id": "",
            "handle": "api_variant_handle",
            "type": "",
            "has_variants": true,
            "variant_parent_id": "",
            "variant_option_one_name": "sample_color",
            "variant_option_one_value": "yellow",
        ...
        },
        {
          "id": "06bf537b-c783-11e6-f6b9-85d842b2f7a5",
            "source_id": "",
            "variant_source_id": "",
            "handle": "api_variant_handle",
            "type": "",
            "has_variants": false,
            "variant_parent_id": "06bf537b-c783-11e6-f6b9-85d5ab5a0c45",
            "variant_option_one_name": "sample_color",
            "variant_option_one_value": "orange"
        ...
        },
        {
            "id": "06bf537b-c783-11e6-f6b9-85d80bdc36c0",
            "source_id": "",
            "variant_source_id": "",
            "handle": "api_variant_handle",
            "type": "",
            "has_variants": false,
            "variant_parent_id": "06bf537b-c783-11e6-f6b9-85d5ab5a0c45",
            "variant_option_one_name": "sample_color",
            "variant_option_one_value": "red"
        ...
        }
    ]
}

6. Results

That's that the final result will look like in the web application:

WARNING: In order to delete the main product, all variants need to be deleted first.\n- Variants can't be re-assigned from one parent to another.\n- Every product can have up to 200 variants. Attempting to create more any more variants will cause an error.