Creating Variants
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_orderas 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_namevalue 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.
Updated 5 months ago