Variants, Variant Options, and Modifier Options
In Catalog API, we make a distinction between two types of product options: variant options and modifier options. It is important to understand when to use a variant option and when to use a modifier option.
In this section, we will discuss what variant options are, when to use variant options, the difference between a base variant and child variants, when to use modifier options, and making adjustments like changes in price.
Creating a product and all of its variants/modifiers at once is the most common way/best practice when possible; however, there are times in which you may need to know how to create each individually.
Variants
Variants represent an item that sits on the shelf in the warehouse or a particular sellable product. A product might be a shirt, while the variant would be “a small, red shirt.”
Variants are selected by shoppers on the storefront via product options. In the case where a product is simple, or without options, the product is its own variant — called a base variant.
Variant Options
Variant options are choices that are used to build out variants. For example, a product might have the variant options size and color.
Each option will then have a list of values. These are the actual selections that are available for an option. For example, the variant option size might have the values small, medium, and large and the variant option color might have the values red, green, and blue. Variant options will automatically generate variants when created in the control panel.
To manage your product catalog effectively using the BigCommerce Catalog API, you will need to create variants explicitly. This means that each variant of a product requires its own individual creation within the API.
Create Variant Options
Create a variant option by sending a POST request to /catalog/products/{product_id}/options
Example:
Required Fields:
display_nametypeoption_values
The response is reformatted using a combination of the display name, a timestamp, and the product id.
GET All Variant Options
Returns a list of product options.
Example:
Variants
Every purchasable entity in the catalog has a variant representation, even products without options. When you create a product without any options, the platform automatically creates a base variant for the base product.
This enhances flow around inventory management, like the ability to solely use the variants endpoint to manage inventory levels.
GET All Product Variants
Returns a list of product variants.
Example:
Create a Product Variant
Creates a product variant.
Example:
Required Fields:
skuoption_values
Variants need to be created one at a time using this endpoint. To use a variant array and create products and variants in the same call use the /catalog/products endpoint during the initial product creation.
Make note of the ids highlighted in the response. You will need them in the next activity.
The values depend on the response in the previous knowledge check.
Base Variant vs. Child Variant
Every purchasable entity in the catalog has a variant representation, even products without options. When you create a product without any options, the platform automatically creates a base variant for the base product.
This enhances flow around inventory management, like the ability to solely use the variants endpoint to manage inventory levels.
In other words, a base variant refers to the variant representation of a simple product with no defined variant options. This is important as it enables the /variants endpoint on simple products and assigns simple products a variant id. Allowing a simple product to be represented as a variant and with a Variant id, helps to make development more efficient.
How are variants used?
- They can be used for tracking inventory (I care when I run out of small, red shirts — I need to re-stock!)
- They can have their own price, weight, dimensions, image, etc — or they can inherit these values from the product if they have not been specified
- They must have a SKU code (unless they’re a base variant)
- In the case of non-base variants, variants will relate to a particular combination of variant option values — such as “small” and “red”
Modifier Options
A modifier option is any choice a shopper can make that doesn’t affect the variant that’s selected.
If I want to create a checkbox for example, “add $5 for shipping insurance”, that doesn’t change which item I go and pick off the shelf, that just changes how I send it to you.
Modifier options are any choices that the shopper can make that will change the way the merchant fulfills the product. Examples include:
- A checkbox to add shipping insurance
- Text to be engraved on the product
- A color that an unfinished product is to be painted before it’s shipped
Critically, the modifier will not change the SKU/variant being fulfilled, and you cannot track inventory against combinations of modifier values. Modifiers typically would not change which product is “picked off the shelf” in the warehouse, but they change what happens to that product before it’s sent to the shopper, or how it’s sent.
Modifier options may be required or non-required. They support all option types but they cannot be used as part of a variant.
Create a Modifier Option
Add a modifier option to a product with a POST request to /catalog/products/{product_id}/modifiers
Example:
https://api.bigcommerce.com/stores/{{store_hash}}/v3/**catalog/products/{product_id}/modifiers**
Required Fields:
required- Whether or not this modifier option is required before a shopper can checkoutdisplay_nametype
Click the CONTINUE button below to send the POST request to add a modifier option to a product:
Adjusters
An adjuster can be added to a modifier option or a variant to change things such as increasing the price or changing the weight. Adjusters cannot be applied to all modifier types.
Adjusters can only be added to multiple choice, pick list, or checkbox modifier options.
Adjusters are needed to apply additional charges for custom options, as product modifiers don’t automatically create new product variants.
Update a Modifier Option
Updates a modifier option.
Remember that in general, variant options help select whatever variant is being added to the cart and modifier options change how that variant is fulfilled.
The image below is a good visual representation of the difference between variants, variant options, modifier options, and adjusters.
To see variants, variant options, or modifier options on a product, you can send a GET request using the v3 API and a REST client such as Postman to:
https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/{productId}/variants
https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/{productId}/options
https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/{productId}/modifiers
