dynamic

Dynamic bundles allow merchandisers to create configurable product groupings where shoppers can personalize selections within defined rules. These bundles are composed of components—logical groupings of related product options—each with customizable constraints and behaviors. This flexible structure enables tailored experiences, driving higher engagement and average order value.

Core Concepts

Component Level Rules

Rules can be defined for each component to control shopper selections:

• Minimum Selections: Require at least a certain number of products that can be chosen within a component.
• Maximum Selections: Limit the number of products a shopper can pick from a component.
• Optional Components: Components can also be optional by setting the minimum selection to zero.

Product Option Quantity Rules

Merchants can define rules for each product within a component to control shopper purchase quantity:

• Default Quantity: If you do not set a minimum or maximum quantity for a component option, the shopper will be limited to the default quantity that you have set for that specific option within the bundle configuration. This is useful when you want to ensure a specific number of a particular item is included if the shopper selects it.
• Minimum Quantity: This sets the lowest number of units a shopper must select for a product option.
• Maximum Quantity: This defines the highest number of units a shopper can select for a product option.

Product Option Defaults

Specific product options can be designated as default within each component. This is particularly useful when the bundle is initially displayed in the cart or when a shopper hasn't yet customized their choices.

Parent Products as Options

When working with products that have variations (such as clothing items with different sizes and colors), you can add the parent product to a bundle component. This automatically makes all child products (variations) available for selection within that component.

Additionally, you can configure specific child products to be excluded from the bundle when the parent is added. This gives you fine-grained control over which variations are available for selection within the bundle, while still benefiting from the convenience of adding the parent product.

For example, if you add a "T-Shirt" parent product to a bundle component, all its variations (Small/Red, Medium/Blue, Large/Black, etc.) become available for selection. However, you might want to exclude certain variations (e.g., Small/Green and Medium/Yellow) from this particular bundle. You can configure these specific child products as exclusions, ensuring they won't appear as options even though the parent product is included.

Bundle Configuration in Catalog and Cart

Dynamic bundles have a bundle_configuration which describes the options selected by a shopper. This configuration is crucial for both displaying bundle options in your catalog and processing bundle purchases in your cart.

Bundle Configuration Structure

The bundle_configuration is a JSON object that contains:

• selected_options: An object where each key is a component ID (e.g., "size", "color", "extras")
  • Each component contains key-value pairs where:
    • The key is the product ID of the selected option
    • The value is the quantity of that option

Working with Bundle Configurations in Catalogs

1. Once your bundles are published in a catalog, a shopper can select the products they want.
2. Use Get a product in a catalog release to check a bundle's default configuration. The default bundle_configuration is returned in the meta section of the response.
3. Use the configure a shopper bundle endpoint to store a shopper's selections.

When adding a dynamic bundle to a cart, you need to include the bundle_configuration in the cart item. This ensures that the correct products and quantities are added to the cart.