About Product Options and Variants

Product options and variants allow merchants to offer product variations to their customers. Options define the ways a product can vary, such as size or color, while variants represent each specific purchasable combination of those options. Understanding how these concepts work together is essential for building e-commerce apps that manage product catalogs effectively.

Key concepts

The Catalog V3 API uses several related terms when working with product variations. Here's how they fit together:

• Option: A product attribute that customers choose from, like "Size" or "Color". Each option has predefined choices.
• Modifier: A customization that collects information from customers without creating separate variants. For example, a gift message or engraving text.
• Choice: A specific value in an option or modifier. For example, "Red", "Blue", and "Green" are choices in a "Color" option.
• Variant: A specific purchasable version of a product. Each variant represents a unique combination of option choices and can have its own price, SKU, inventory, and other properties.
• Customization: A reusable entity that can be either an option or a modifier. Customizations are stored independently and can be assigned to multiple products. These are managed with the Customizations API.

How options and variants work together

When you add options to a product, you must also provide the corresponding variants. Variants aren't automatically generated. You must explicitly define each option-choice combination. Each variant must reference exactly 1 choice from each option defined on the product.

While the API technically allows creating fewer variants than the total possible combinations, we recommend that you create a variant for every combination to ensure customers can purchase any selection they make. For example, for a product with 2 options, such as Color with 2 choices and Size with 3 choices, we recommend that you create all 6 variants to cover every combination.

Products can have up to 6 options and up to 1,000 variants.

Products without options

Every product has at least 1 variant. Products without options have a single "default variant" with an empty choices array. This default variant holds the product's price, SKU, and other variant-level data.

Options vs modifiers

Options and modifiers both allow customers to make selections, but they serve different purposes:

Use options when:

• Different selections require different inventory tracking.
• Each combination should have its own SKU or barcode.
• Pricing varies based on the selection.

Use modifiers when:

• You need to collect additional information without affecting inventory.
• You want to offer optional add-ons with a fixed price increase.
• The selection doesn't represent a fundamentally different product version.

Render types

Both options and modifiers can be displayed to customers in different ways, called render types:

Text choices

Displays choices as text labels. Best for selections like sizes such as S, M, and L, or materials such as Cotton and Silk.

Swatch choices

Display choices as color swatches. Use for color selections where visual representation is important.

Free text for modifiers

Allow customers to enter custom text. Use for personalization like gift messages or engraving.

Customizations

Options and modifiers are stored as customization entities that you can create and manage using the Customizations API. Customizations can be created independently and reused across multiple products. When you create a product with inline options or modifiers without referencing existing customization IDs, the system automatically creates standalone customization entities.

Direct customization creation

You can create customizations before assigning them to products:

Customization reuse

Existing customizations can be assigned to a product by referencing their id in the product's options or modifiers array:

Customization types

Customizations have 1 of 2 types:

• PRODUCT_OPTION: Creates variants and affects inventory.
• MODIFIER: Collects information without creating variants.

You can't change the customization type after you create it.

Variant structure

When creating a product with options, you must explicitly provide every variant you want to sell. The API doesn't auto-generate variants from option choices. Each variant references its option choices using optionChoiceNames in the request, and the API returns the corresponding optionChoiceIds in the response:

Variant-level properties

Each variant can have its own:

• Price: Current selling price, stored in actualPrice, and original price, stored in compareAtPrice.
• SKU and barcode: Unique identifiers for inventory tracking.
• Visibility: Whether the variant is shown to customers.
• Physical properties: Weight and price-per-unit settings for physical products.
• Digital file: Downloadable content for digital products.
• Revenue details: Cost of goods for profit calculations.

Example product with options, modifiers, and variants

The following example shows a yoga mat product with a Color swatch option and a Thickness text option, plus a free-text modifier for personalization. Since the product has 2 colors × 2 thicknesses, it includes all 4 variants:

In this example:

• The Color option uses SWATCH_CHOICES with hex color codes for visual selection.
• The Thickness option uses TEXT_CHOICES for text-based selection.
• The Personalization modifier uses FREE_TEXT to collect custom text with a $5 upcharge.
• All 4 variants are created to cover every possible combination of 2 colors × 2 thicknesses: Purple/4mm, Purple/6mm, Teal/4mm, and Teal/6mm.
• The 6mm variants cost $10 more and weigh 0.5kg more than the 4mm variants.
• Physical products require an empty physicalProperties: {} object at the product level, with optional properties like weight at the variant level.

Linked media

You can associate specific product images with option choices using linkedMedia. When a customer selects a choice, only the linked media is shown:

When multiple choices are selected, for example "Color: Red" and "Material: Silk", only media that appears in the linkedMedia of all selected choices is displayed.

Variants and inventory

Inventory is managed separately from products through the Inventory Items API. Each inventory item is linked to a specific variant and location, meaning the same variant can have different stock levels at different warehouse or store locations.

When you create variants, the system doesn't automatically create inventory items. You must create inventory items separately for each variant-location combination you want to track. Without inventory items, a variant has no stock information.

The Products API includes some read-only inventory fields that reflect the aggregated inventory status across all locations, but to manage stock levels, use the Inventory Items API.

Read-only variants

The Read-Only Variants API provides direct access to variants, rather than as nested objects in products. This is useful for:

• Building variant-focused inventory management interfaces.
• Implementing variant search and filtering.
• Syncing variant data with external systems.

Deletion behavior

Options and modifiers have different deletion behaviors:

• Options can't be deleted while assigned to any product because they affect variants and inventory.
• You can delete modifiers freely. When you delete a modifier, the system automatically removes it from all products that reference it.
• You can't remove choices in options if they're assigned to 1 or more product variants.
• You can remove choices in modifiers freely.

See also

• Products API
• Customizations API
• Read-Only Variants API
• Inventory Items API