Creating a product in BigCommerce via the REST API is generally straightforward — it requires only a single API request.

However, creating variants is more involved. Variants depend on variant options and option values, which must exist before the variant itself can be created.

This guide walks through the recommended step-by-step flow for creating product variants in BigCommerce.

---

Step 1: Create (or Retrieve) the Product

Before creating variants, a product must exist. You can either:

• Create a product¹
• Or retrieve an existing product

Once you have a product_id, you can begin creating variant options.

Step 2: Create or Validate Variant Options

Variants are built from variant options (like Size or Color), which contain option values (like Small, Medium, Large).

Before creating variant option values, a variant option must exist. You can either:

• Create a variant option²
• Or retrieve an existing variant option

Note: Modifying option values requires an option_id. It is common to fetch a product option by name or display_name, since option_id may not be readily available. To obtain an option’s option_id, first retrieve all variant options, then parse the results to find the matching option.

Once you have an option_id, you can begin creating variant option values.

Step 3: Create or Validate Option Values

Each variant option must have option values.

For example:

• Option: Size
• Option Values: Small, Medium, Large

You can now create a variant option value.

Recommended workflow:

1. Retrieve existing option values.
2. If a value does not exist, create it.
3. (Optional) Delete values that are no longer needed.

Note: Renaming option values is possible but requires careful mapping logic to determine whether a value should be updated, deleted, or recreated.

Step 4: Create Variants

Once all variant options and all variant option values exist, you can create a variant.

Each variant must reference a list of the appropriate option_values.

In most cases, you will want to create variants for every combination of option values (e.g., Small/Red, Small/Blue, Medium/Red, etc.).

Technically, BigCommerce does not require that you create every possible combination. However, I have observed that when viewing the product in the BigCommerce Admin UI, the system may automatically generate missing variant combinations if they do not already exist.

---

Shortcut: Nested Creation

The following endpoints allow nested creation:

• Product creation can include a variants array.
• Option creation can include an option_values array.

This reduces the number of API calls required. However, this approach often results in separate flows for:

• Initial product creation
• Ongoing product/variant updates

If you want a single consistent workflow for both create and update operations, it is better to break the process into discrete steps:

• Ensure option exists (create/delete as needed)
• Ensure option values exist (create/delete as needed)
• Create/update variants

Recommendation: Avoid using nested creation shortcuts when building middleware integrations, as doing so necessitates maintaining separate logic paths for create and update operations. Using a consistent approach simplifies long-term maintenance and reduces edge-case complexity.

---

Recommended Consistent Workflow

For systems that regularly sync product data:

1. Check for the option
   • If it doesn’t exist, create it (without values).
2. Check option values
   • Create missing values.
   • Optionally remove values that are no longer valid.
3. Create the desired variants
   • Usually generate all combinations of option values.
   • Pass the appropriate option_values.

This approach ensures predictable, idempotent behavior and works well for both creation and updates.

---

Extending Variant Data

Once created, variants can be extended with non-native properties via variant metafields.

---