Skip to main content

Bundles Overview

Product bundles allow you to group multiple products together as a single purchasable unit. Elastic Path supports both fixed bundles (predefined selections) and dynamic bundles (shopper-configurable options), enabling powerful cross-sell opportunities and customizable product offerings.

Common Use Cases​

Bundles are ideal for products that are commonly purchased together or benefit from configuration:

  • Computer Builds: Base unit with configurable RAM, storage, graphics card options
  • Gift Sets: Curated collections with optional add-ons (gift wrap, cards, premium packaging)
  • Meal Kits: Base ingredients with optional sides, desserts, or dietary alternatives
  • Camera Packages: Camera body with lens, bag, and accessory options
  • Furniture Sets: Sofa with configurable cushions, ottomans, and accent pieces
  • Subscription Boxes: Core items with customizable preferences

When to Use Bundles​

Use Bundles When:​

  • Products are frequently purchased together
  • You want to offer bulk discounts on grouped items
  • Customers benefit from pre-configured selections
  • You need flexible product customization
  • Cross-selling complementary products is important
  • Managing inventory for component products separately

Don't Use Bundles When:​

  • Products have interdependent variations (use Product Variations instead)
  • The combination creates a fundamentally different product
  • Component products don't make sense individually
  • You need more than one level of nesting

Key Benefits​

Using bundles provides several advantages over selling products individually:

  • Increased Average Order Value: Encourage larger purchases through bundled offerings
  • Simplified Shopping: Pre-configured options reduce decision fatigue
  • Flexible Customization: Let shoppers personalize within defined parameters
  • Inventory Efficiency: Components remain as separate SKUs for easier management
  • Dynamic Pricing: Offer bundle discounts or calculate prices from components
  • Better User Experience: Guide customers to complete solutions

Bundle Types Explained​

Fixed Bundles​

Fixed bundles contain a predefined set of products with no shopper customization. They have components but without min/max selection requirements:

Use Cases: Starter kits, value packs, curated collections

Dynamic Bundles​

Dynamic bundles allow shoppers to configure their selection. They have components with min and/or max selection requirements:

Component Types:

  • Required: Must select specified number of options
  • Optional: Can skip or select up to maximum
  • Multi-select: Can choose multiple options with min/max limits

Bundle of Bundles​

One level of bundle nesting for complex product hierarchies:

Important: Each child bundle is configured and purchased separately

Frontend Implementation Overview​

When building bundle selection in your storefront, consider these critical aspects:

Component Selection Flow​

Key Data Structures​

Understanding bundle data is crucial for implementation:

// Bundle product structure
interface BundleProduct {
  id: string
  type: "bundle"
  attributes: {
    name: string
    components: {
      [key: string]: ComponentProduct
    }
  }
  meta: {
    product_types: string[]  // First element indicates type: 'bundle'
    bundle_configuration?: {
      selected_options: BundleConfiguration["selected_options"]
    }
  }
}

// Component structure
interface ComponentProduct {
  name: string
  options: ComponentProductOption[]
  min?: number  // Minimum selections required
  max?: number  // Maximum selections allowed
  sort_order?: number
}

// Component option structure
interface ComponentProductOption {
  id: string
  quantity?: number
  type: 'product'
  sort_order?: number
}

// Selected configuration
interface BundleConfiguration {
  selected_options: {
    [componentKey: string]: {
      [optionId: string]: number  // quantity
    }
  }
}

Critical Implementation Points​

Configuration State Management​

  • Bundle configuration must be sent when adding to cart
  • Use configureByContextProduct API to validate selections
  • Configuration affects final price calculation

Price Updates​

  • Dynamic bundles require real-time price recalculation
  • Show loading states during price updates
  • Handle both explicit and auto-pricing models

Validation Requirements​

  • Enforce min/max selection rules per component
  • Validate all required components have selections
  • Provide clear error messaging for invalid configurations

Cart Operations​

  • Bundle configuration is required for dynamic bundles
  • Each bundle in cart maintains its configuration
  • Bundle components are tracked separately for inventory

Bundle Pricing Models​

Explicit Pricing​

Bundle has a fixed price regardless of component selection:

// Bundle price set in PXM
bundle.attributes.price = {
  USD: { amount: 99900, includes_tax: false }
}

Auto/Cumulative Pricing​

Total calculated from selected component prices:

// Price updates based on selection
const totalPrice = selectedComponents.reduce(
  (sum, component) => sum + component.price * component.quantity,
  0
)

For detailed pricing implementation, see Bundle Pricing Strategies.

Common Frontend Patterns​

Choose the right selection pattern based on your needs:

PatternBest ForComplexity
Checkbox GridVisual products, quick selection🟢 Simple
Step-by-Step WizardComplex bundles, guided experience🟡 Moderate
Accordion ViewMany components, space-constrained🟢 Simple
Visual BuilderCustomizable products, drag-drop🔴 Complex

For implementation examples and code, see Bundle Selection Patterns.

Common Frontend Pitfalls​

Avoid these common mistakes when implementing bundles:

1. Not Validating Component Requirements​

// ❌ Wrong: Adding to cart without validation
addToCart(bundleId, configuration);

// ✅ Correct: Validate requirements first
if (validateBundleConfiguration(components, configuration)) {
  addToCart(bundleId, configuration);
}

2. Ignoring Price Update States​

// ❌ Wrong: No feedback during price calculation
updateConfiguration(newConfig);

// ✅ Correct: Show loading state
setIsPriceUpdating(true);
const updatedBundle = await configureBundle(newConfig);
setIsPriceUpdating(false);

3. Not Handling Configuration Persistence​

// ❌ Wrong: Configuration lost on page refresh

// ✅ Correct: Persist to URL or session
const configString = btoa(JSON.stringify(configuration));
router.push(`/bundle/${bundleId}?config=${configString}`);

4. Forgetting Error States​

// ❌ Wrong: Silent failures
const result = await addBundleToCart(data);

// ✅ Correct: Handle errors explicitly
try {
  const result = await addBundleToCart(data);
  showSuccess("Bundle added to cart!");
} catch (error) {
  showError("Failed to add bundle. Please check your selections.");
}

Troubleshooting​

Common Issues and Solutions​

"Bundle configuration is required" error​

  • Cause: Attempting to add dynamic bundle without configuration
  • Solution: Ensure bundle_configuration is included in cart request

Price not updating with selection changes​

  • Cause: Not calling configure API after selection change
  • Solution: Use configureByContextProduct after each change

Component products not showing​

  • Cause: Missing includes, unpublished catalog, or incorrect product type detection
  • Solution: Ensure catalog is published, use proper includes, and check products with meta.product_types[0] === 'bundle'

Validation errors not showing​

  • Cause: Not checking component min/max requirements
  • Solution: Implement client-side validation before API calls

Learning Path​

Follow this recommended path to master bundle implementation:

  1. Handling Bundle Types
    Learn to detect and handle different bundle types

  2. Get Bundle Product Data
    Fetch bundle data with components and images

  3. List Bundle Components
    Display bundle components with their options

  4. Configure Dynamic Bundles
    Implement component selection and configuration

  5. Understanding Bundle Configuration (Advanced)
    Deep dive into configuration structure and validation

  6. Bundle Selection Patterns
    Choose and implement the best UI pattern for your needs

  7. Bundle Pricing Strategies
    Understand pricing models and display dynamic prices

  8. Add Bundle to Cart
    Complete the purchase flow with bundle configuration

Next Steps​

How-To Guides​

References​