Add product data using the new product model

In this guide, you'll learn how to create a new product with multiple options, option values, and variants, using either a single mutation or multiple mutations.

You'll also learn the workflow for creating a product and its variants and operations using updated product operations.

You want to create a product with the following data:

• Two options:

  • Color
  • Size

• Each option has three option values:

  • Color has Red, Green, and Blue
  • Size has Small, Medium, and Large

• Each option value has a variant, for nine product variants total, representing all possible combinations of option values. For example:

  • Red / Small
  • Blue / Large

The following diagram represents the desired shape of the product data:

The diagram displays the "OptionValues" that are assigned to each variant, and the "Values" that belong to each "Option" relationship of the product's variants to their option values. On the right, there's the relationship of the product's options to their option values. The values that are represented in "OptionValues" correspond with a value in the product's options.

The following is the corresponding data structure:

To create a product with incremental mutations, run the productCreate mutation to create a standalone product variant and the productVariantsBulkCreate mutation to overwrite this data.

The following example creates a product with color and size options, including the options' values. The productCreate mutation creates the product, the options, the option values, and a single variant that's assigned the first combination of option values. This is the standalone variant.

In this example, the standalone variant has a Color value of Red and a Size value of Small. The title is automatically set to Red / Small.

When options have more than one optionValue, the productCreate mutation sets the first variant to have the first option value and retains all other option values as orphaned option values.

After running the mutation successfully and obtaining the product ID, you can use the productVariantsBulkCreate mutation to create the remaining product variants and map them to the existing options.

You can create up to 250 variants in a single batch using this mutation. In cases where you need to create a higher volume of variants, you need to run the mutation multiple times. Learn how to use fragments and cursor-based pagination to help do this efficiently.

To return only the variants that were added, and not all of the product variants, the example uses the productVariants field.

To overwrite the standalone variant that was created in the initial productCreate mutation, run the productVariantsBulkCreate mutation with a strategy of REMOVE_STANDALONE_VARIANT.

If you're using API version 2024-01 and lower, and you need to create a product with many variants that are active at several locations, especially with a lot of collections and tags, then you should first create the product with just the variants.

After the product is created, you can activate the variants at locations and add the other related objects to the product. This reduces the size of each mutation and increases the likelihood that it will complete before the operation times out.

The following example shows how you might break up product creation and object association into multiple steps:

1. Create the product with variants. Don't specify any tags or collections on the product, and don't specify inventory quantities for each variant.

2. After the product is created, add tags to the product using the tagsAdd mutation, and add collections using the collectionsAddProducts mutation.

3. Use the inventoryBulkToggleActivation mutation on each inventory item to activate it at the appropriate locations.

4. After activating the variants at the locations, adjust inventory quantities for the inventory items using the inventoryAdjustQuantities mutation.