About the Customizations API

The Customizations API allows you to create and manage product customizations, which include options and modifiers. These can be applied to products to allow customers to customize, select a specific product variant, or add on to a product.

Customizations can be either options or modifiers:

• Options create product variants that affect inventory, SKU, and pricing. For example, a "Size" option with "Small", "Medium", "Large" choices creates three variants.
• Modifiers collect additional information from customers without creating variants. For example, a "Gift Message" modifier allows customers to enter text.

For a comprehensive explanation of options, modifiers, and variants, see About Product Options and Variants.

With the Customizations API, you can:

• Create and manage reusable customizations.
• Retrieve information about existing customizations.
• Delete existing customizations.

Customizations and products

Customizations can be created independently and then assigned to products, or they can be created inline when creating a product. When you create a product with inline options or modifiers (without referencing existing customization IDs), new standalone customization entities are automatically created, which can then be reused across other products.

Deleting customizations

Options and modifiers have different deletion behavior:

• Options can't be deleted while assigned to any product, because they affect product variants and inventory.
• Modifiers can be deleted freely. When a modifier is deleted, it's automatically removed from all products that reference it.

Deleting choices

Choices within options can't be removed if they're assigned to one or more product variants. Choices within modifiers can be removed freely.

Choice grouping with primary choices

Choices can be organized into primary-linked groups using primaryChoiceIds. This is useful for storefront filtering, where related choices are grouped under a primary choice. For example, a "Color" option might have a "Blue" primary choice with "Navy Blue", "Sky Blue", and "Royal Blue" as linked choices.

Key points about choice grouping:

• A linked choice is excluded from the top-level storefront filter list and displayed under its primary choice's group instead.
• A linked choice can belong to multiple primaries, appearing under each primary group.
• Only a single level of grouping is supported. A choice that is a primary of other choices can't also be a linked choice.
• Removing a primary choice that is still referenced by linked choices isn't allowed. Update or remove the linked choices first.
• Use Update Customization Choices to set primaryChoiceIds on existing choices.

Choice sort order

You can control how a customization's choices are displayed in storefront filter panels by setting a sort order. The available strategies are:

• Default: Text choices are sorted by name, swatch choices are sorted by product count.
• By name: Alphabetical order, case-insensitive.
• By product count: Choices with the most assigned products appear first.
• Manual: You specify the exact display order by providing the choice IDs in your preferred sequence. Use Reorder Customization Choices to set the order. Calling this endpoint sets the sort order to MANUAL.

For all strategies except manual, the sort order is applied at display time — the underlying choices list isn't modified. For manual sorting, the choices list is reordered and persisted via Reorder Customization Choices.

Before you begin

It's important to note the following points before starting to code:

• The Wix user must install the Wix Stores app.

Use cases

• Set up customizations for a clothing store
• Create a product with new options
• Create a product with new modifiers
• Group choices under a primary choice
• Set the sort order for choices in storefront filters

Terminology

For a comprehensive glossary of Catalog V3 terms, see Terminology.