Multi-Step Bundles

Multi-Step Bundles: Step & Gift Configuration Summary

Concept: Multi-step bundles break the bundle-building experience into multiple guided steps (tabs), such as "Choose Your Base", "Pick Your Add-Ons", and "Select a Gift". Each step is represented by a BundleStep record.

How Steps Work

• Steps are shown as tabs in the bundle widget.
• Customers move step-by-step to build their bundle.
• Steps are ordered by their position field (0-based). The step with position: 0 is the default active tab.

Each BundleStep has its own:

• Product pool (products or collections specific to that step)
• Quantity rules (independent min/max per step)
• Selection type (products, variants, or collections)
• Display options (e.g., show variants as individual cards)

Adding & Managing Steps

Creating a New Step

When you click Add Step on the bundle edit page, a new step is created with:

• Name: "Step 1" (auto-incremented for subsequent steps)
• Position: Next available integer position
• Min Quantity (minQuantity): 1
• Max Quantity (maxQuantity): null (unlimited)
• Selection Type (selectionType): "products"

Reordering Steps

• Drag and drop steps to change their order.
• position Values update automatically.
• The step with position: 0 the initial active tab when the widget loads.

Removing Steps

• Click the delete icon on a step to remove it.
• All eligible/compulsory items within that step are removed as well.
• You must always have at least one step in a bundle.

Step Configuration Options

Selection Type (selectionType)

Defines how the step sources products:

• Products — selectionType: "products"
• Manually curated list of specific products.
• Collections — selectionType: "collections"
• Dynamically pulls products from linked Shopify collections.

Quantity Rules

Control how many items can/must be selected in a step:

• Step Min Quantity — minQuantity
• Minimum number of items required in this step.
• Default: 1.
• Step Max Quantity — maxQuantity
• Maximum number of items allowed in this step.
• null = unlimited.
• Per-Product Min — productMinQuantity
• Minimum quantity of any single product.
• Default: 1.
• Per-Product Max — productMaxQuantity
• Maximum quantity of any single product.
• null = unlimited.

Tip: Set productMaxQuantity = 1 to force customers to choose different products instead of multiples of the same item.

Show Variants as Cards (showVariantsAsCards)

• Enabled (true): Each variant appears as its own card in the grid (ideal when variants have distinct images, e.g., colors).
• Disabled (false, default): Variants are shown as a dropdown or button group inside a single product card.

Step Image

• Each step includes an option to upload or select an image
• When an image is added, it will be displayed alongside the step name in step tab
• This helps customers easily identify and navigate between steps