Customizations API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Set up customizations for a clothing store

1. Create a Customization with type PRODUCT_OPTION, and with different product colors (choices): red, green, blue.
   • Render type must be SWATCH_CHOICES and choice type must be ONE_COLOR.
   Copy

2. Create a Customization, with type PRODUCT_OPTION, and with different product sizes (choices): S, M, L, XL.
   • Customization render type must be TEXT_CHOICES and choice types must be CHOICE_TEXT.
   Copy

3. Create a Customization, with type MODIFIER, in order to specify free text to be on a product.
   • Render type must be FREE_TEXT.
   • Set freeTextInput.title to "Choose text to be on shirt", and have and a range of 10-50 characters.
   Copy

4. Add customization choices to the Color customization (for example, add yellow).
   Copy

5. Query for all the customizations of type PRODUCT_OPTION and render type SWATCH_CHOICES.

Create a product with new options

To assign a new non-existing option to a new product, you can provide the option to the Create Product request.

To create a product with new options, call Create Product and pass the name, optionRenderType, and choices:

Create a product with new modifiers

To assign a new non-existing modifier to a new product, you can provide the modifier to the Create Product request.

To create a product with new modifiers, call Create Product and pass the name, modifierRenderType, and freeTextSettings:

Update an option name

To change the name of an option, which updates all products to which it is assigned, call Update Customization with the requested changes:

Delete a modifier

To delete a modifier, which removes it from any product to which it is assigned, call Delete Customization with the customizationId of the modifier you want to delete:

Group choices under a primary choice

You can organize related choices into groups for storefront filtering. For example, if a "Color" option has many shades of blue, you can group them under a "Blue" primary choice so that customers see a cleaner filter list.

To group choices under a primary choice:

1. Call Create Customization with all the choices you need, including the primary and linked choices:

   Copy

2. Note the choice IDs from the response. For example, "Blue" gets ID aaa..., "Navy Blue" gets bbb..., and "Sky Blue" gets ccc....

3. Call Update Customization Choices to assign primaryChoiceIds to the linked choices. Set the primaryChoiceIds of "Navy Blue" and "Sky Blue" to the ID of "Blue":

   Copy

4. In the storefront filter, "Navy Blue" and "Sky Blue" are now grouped under "Blue" instead of appearing as separate top-level filter options.

Set the sort order for choices in storefront filters

You can control how a customization's choices appear in storefront filter panels by setting a sort order. You can also manually reorder the choices list.

To set the sort strategy:

1. Call Get Customization to retrieve the customization and its current revision.
2. Call Update Customization with the desired choicesSettings.sortOrder. For example, to sort alphabetically by name:
   Copy

To manually reorder choices:

1. Call Get Customization to retrieve the customization, its current revision, and choice IDs.
2. Call Reorder Customization Choices with all current choice IDs in the desired display order. This sets sortOrder to MANUAL:
   Copy