> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt ## Resource: About Product Options and Variants ## Article: About Product Options and Variants ## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/about-product-options-and-variants.md ## Article Content: # 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](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/customizations-v3/introduction.md). ## 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. | Options | Combinations and Variants Needed | |---------|-------------------------------| | Color: Red, Blue + Size: S, M, L | 6 | | Color: Red, Blue + Size: S, L | 4 | 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: | Feature | Options | Modifiers | |---------|---------|-----------| | Creates variants | Yes | No | | Affects inventory | Yes | No | | Has its own SKU | Yes, per variant | No | | Has its own price | Yes, per variant | Optional price add-on | | Example use cases | Size, Color, Material | Gift message, Engraving, "Remove price tag" | 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. ```json { "name": "Size", "optionRenderType": "TEXT_CHOICES", "choicesSettings": { "choices": [ { "choiceType": "CHOICE_TEXT", "name": "S" }, { "choiceType": "CHOICE_TEXT", "name": "M" }, { "choiceType": "CHOICE_TEXT", "name": "L" } ] } } ``` ### Swatch choices Display choices as color swatches. Use for color selections where visual representation is important. ```json { "name": "Color", "optionRenderType": "SWATCH_CHOICES", "choicesSettings": { "choices": [ { "choiceType": "ONE_COLOR", "name": "Red", "colorCode": "#FF0000" }, { "choiceType": "ONE_COLOR", "name": "Blue", "colorCode": "#0000FF" } ] } } ``` ### Free text for modifiers Allow customers to enter custom text. Use for personalization like gift messages or engraving. ```json { "name": "Gift message", "modifierRenderType": "FREE_TEXT", "mandatory": false, "freeTextSettings": { "minCharCount": 0, "maxCharCount": 200, "title": "Enter your gift message" } } ``` ## Customizations Options and modifiers are stored as customization entities that you can create and manage using the [Customizations API](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/customizations-v3/introduction.md). 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: ```json { "name": "Size", "customizationType": "PRODUCT_OPTION", "customizationRenderType": "TEXT_CHOICES", "choicesSettings": { "choices": [ { "choiceType": "CHOICE_TEXT", "name": "Small" }, { "choiceType": "CHOICE_TEXT", "name": "Medium" }, { "choiceType": "CHOICE_TEXT", "name": "Large" } ] } } ``` ### Customization reuse Existing customizations can be assigned to a product by referencing their `id` in the product's `options` or `modifiers` array: ```json { "options": [ { "id": "existing-size-customization-id" } ] } ``` ### 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: ```json { "variantsInfo": { "variants": [ { "visible": true, "sku": "SHIRT-S-RED", "choices": [ { "optionChoiceNames": { "optionName": "Size", "choiceName": "S", "renderType": "TEXT_CHOICES" } }, { "optionChoiceNames": { "optionName": "Color", "choiceName": "Red", "renderType": "SWATCH_CHOICES" } } ], "price": { "actualPrice": { "amount": "29.99" } } } ] } } ``` ### 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: ```json { "name": "Premium Yoga Mat", "description": { "nodes": [ { "type": "PARAGRAPH", "id": "desc1", "nodes": [ { "type": "TEXT", "textData": { "text": "Professional-grade yoga mat with superior grip and cushioning." } } ], "paragraphData": { "textStyle": { "textAlignment": "AUTO" } } } ], "metadata": { "version": 1, "id": "yoga-mat-desc" } }, "productType": "PHYSICAL", "physicalProperties": {}, "visible": true, "options": [ { "name": "Color", "optionRenderType": "SWATCH_CHOICES", "choicesSettings": { "choices": [ { "choiceType": "ONE_COLOR", "name": "Purple", "colorCode": "#800080" }, { "choiceType": "ONE_COLOR", "name": "Teal", "colorCode": "#008080" } ] } }, { "name": "Thickness", "optionRenderType": "TEXT_CHOICES", "choicesSettings": { "choices": [ { "choiceType": "CHOICE_TEXT", "name": "4mm" }, { "choiceType": "CHOICE_TEXT", "name": "6mm" } ] } } ], "modifiers": [ { "name": "Personalization", "modifierRenderType": "FREE_TEXT", "mandatory": false, "freeTextSettings": { "minCharCount": 0, "maxCharCount": 20, "title": "Add your name or initials", "defaultAddedPrice": "5.00" } } ], "variantsInfo": { "variants": [ { "visible": true, "sku": "YOGA-PURPLE-4MM", "choices": [ { "optionChoiceNames": { "optionName": "Color", "choiceName": "Purple", "renderType": "SWATCH_CHOICES" } }, { "optionChoiceNames": { "optionName": "Thickness", "choiceName": "4mm", "renderType": "TEXT_CHOICES" } } ], "price": { "actualPrice": { "amount": "39.99" } }, "physicalProperties": { "weight": 1.0 } }, { "visible": true, "sku": "YOGA-PURPLE-6MM", "choices": [ { "optionChoiceNames": { "optionName": "Color", "choiceName": "Purple", "renderType": "SWATCH_CHOICES" } }, { "optionChoiceNames": { "optionName": "Thickness", "choiceName": "6mm", "renderType": "TEXT_CHOICES" } } ], "price": { "actualPrice": { "amount": "49.99" } }, "physicalProperties": { "weight": 1.5 } }, { "visible": true, "sku": "YOGA-TEAL-4MM", "choices": [ { "optionChoiceNames": { "optionName": "Color", "choiceName": "Teal", "renderType": "SWATCH_CHOICES" } }, { "optionChoiceNames": { "optionName": "Thickness", "choiceName": "4mm", "renderType": "TEXT_CHOICES" } } ], "price": { "actualPrice": { "amount": "39.99" } }, "physicalProperties": { "weight": 1.0 } }, { "visible": true, "sku": "YOGA-TEAL-6MM", "choices": [ { "optionChoiceNames": { "optionName": "Color", "choiceName": "Teal", "renderType": "SWATCH_CHOICES" } }, { "optionChoiceNames": { "optionName": "Thickness", "choiceName": "6mm", "renderType": "TEXT_CHOICES" } } ], "price": { "actualPrice": { "amount": "49.99" } }, "physicalProperties": { "weight": 1.5 } } ] } } ``` 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: ```json { "name": "Color", "optionRenderType": "SWATCH_CHOICES", "choicesSettings": { "choices": [ { "choiceType": "ONE_COLOR", "name": "Red", "colorCode": "#FF0000", "linkedMedia": [ { "id": "red-product-image-1" }, { "id": "red-product-image-2" } ] } ] } } ``` 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](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/inventory-items-v3/introduction.md). 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. ## Retrieving variant data Query and Search endpoints in the Products API don't include variants in the response. To retrieve variant data, you must either: - Call [Get Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/get-product.md) or [Get Product By Slug](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/get-product-by-slug.md) for each product individually, which includes full variant information. - Use the [Read-Only Variants API](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/read-only-variants-v3/introduction.md) for variant-centric queries. The Read-Only Variants API provides direct access to variants as standalone entities, which is essential for: - Querying, searching, and filtering variants directly. - Building variant-focused inventory management interfaces. - Syncing variant data with external systems. > **Note:** The Read-Only Variants API operates on an eventually consistent model. Changes made through the Products API sync to this service over time. ## 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](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/introduction.md) - [Customizations API](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/customizations-v3/introduction.md) - [Read-Only Variants API](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/read-only-variants-v3/introduction.md) - [Inventory Items API](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/inventory-items-v3/introduction.md)