> ## Documentation Index
> Fetch the complete documentation index at: https://bundles-docs.getappfox.com/product-bundles/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Mix & Match Bundle (Build-a-Box)

> Let Shopify shoppers build a box in Appfox Mix & Match: they pick products and variants from your pool, with quantity limits and tiered discounts.

Mix & Match Bundles, also known as Build-a-Box, give customers the ultimate flexibility to create their own bundle by choosing products and specific variants from a predefined selection. This is ideal for variety packs, samplers, gift boxes, and fully customizable bundles.

## What is a Mix & Match Bundle?

A Mix & Match Bundle lets customers select a specific quantity of products (with optional variant selection) from a larger pool of options. You define which products are available, set minimum and maximum quantities, and configure tiered discount offers based on the number of items selected.

**Example**: "Choose any 5-10 teas for up to 20% off" or "Build your own 6-pack: Pick 6 protein bars from 12 flavors"

## Key Features

* **Variant Selection**: Customers can choose specific variants (size, color, flavor) for each product they add
* **Flexible Quantities**: Set minimum and maximum product limits
* **Tiered Discounts**: Offer better discounts for larger quantities
* **Multiple Selections**: Customers can add the same product multiple times with different variants
* **Dedicated Build-a-Box Page**: Standalone page with progress indicators and sticky summary
* **Translatable Text**: Customize all UI text for international stores

## When to use Mix & Match Bundles

Mix & Match Bundles work best for:

* **Variety packs**: Letting customers sample different flavors, colors, or variants
* **Samplers**: Try-before-committing bundles
* **Customizable sets**: Giving customers control over their selection
* **Discovery bundles**: Encouraging trial of multiple products

## Creating a Build-a-Box Bundle

<Steps>
  <Step title="Select bundle type">
    From the Bundles page, click **Create a bundle** and select **Mix & Match Bundle**.
  </Step>

  <Step title="Define the product pool">
    Select all products that customers can choose from. Add 3 or more products to give meaningful choice. You can also source products from collections (requires configuration).
  </Step>

  <Step title="Set quantity limits">
    Configure **Minimum Products** and **Maximum Products** to control the box size. For example:

    * Min: 3, Max: 6 allows customers to choose between 3-6 items
    * Min: 5, Max: 10 for larger variety boxes
  </Step>

  <Step title="Configure tiered offers">
    Set up quantity-based discount tiers in **Offer Settings**:

    * 3+ items: 10% OFF
    * 5+ items: 15% OFF
    * 8+ items: 20% OFF

    Supports percentage, flat amount, or fixed price per item discounts.
  </Step>

  <Step title="Name and describe your bundle">
    * **Bundle Name**: Internal reference (e.g., "Tea Sampler Box")
    * **Bundle Title**: Customer-facing title (e.g., "Build Your Perfect Tea Collection")
    * **Subtitle** (optional): Additional description shown below the title
  </Step>

  <Step title="Enable variant selection">
    Check **Allow Variants Selection** to let customers choose specific variants (size, color, flavor) for each product. This allows them to add the same product multiple times with different variants.
  </Step>

  <Step title="Customize text (optional)">
    Under **Display Options**, customize button text and validation messages for your store's language and brand voice.
  </Step>

  <Step title="Get the Build-a-Box page URL">
    After saving, copy the **Build-a-Box Page URL** from the bundle editor to link directly to the standalone builder page.
  </Step>

  <Step title="Activate">
    Toggle to **Active** and click **Save** or **Update Bundle**.
  </Step>
</Steps>

## Bundle settings

### Product pool

* **Minimum products in pool**: 3 (to give customers choice)
* **Recommended**: 6-15 products for optimal choice
* **Product types**: Can mix product types, or keep within one category

### Quantity settings

* **Required quantity**: How many products customers must choose
* **Typical values**: 3, 5, 6, or 10 items
* **Flexibility**: Customers can choose any combination that meets the quantity

### Discount options

**Percentage discount**:

* Enter a percentage (e.g., 20%)
* Applied when customers add the required quantity

**Fixed bundle price**:

* Set a total price (e.g., \$25)
* Customers pay this price regardless of which products they choose
* Great for "Any X for \$Y" offers

## How it appears on your store

### Product page widget

The widget displays:

* Bundle title and subtitle
* Tiered discount offers (e.g., "3+ ITEMS 10% OFF", "5+ ITEMS 20% OFF")
* Grid of available products with images and prices
* Quantity selector for each product (+ / - buttons)
* Variant dropdown (when enabled) showing available options
* Real-time validation messages
* "Add to cart" button (enabled when quantity is within min/max range)

### Dedicated Build-a-Box page

The standalone page (`/apps/bundles?bundle=ID`) includes:

* Progress indicator (3-step visual guide)
* Sticky summary showing:
  * Selected item count / minimum required
  * "Ready to add" status
* Enhanced product grid with hover effects
* Same quantity and variant selection features as the widget
* Full-width "Add to cart" button

### Cart

Customers see:

* Individual line items for each selected product/variant
* Bundle identifier in line item properties
* Discount applied automatically at checkout via Shopify Functions

## Best practices

<AccordionGroup>
  <Accordion title="Give meaningful choice" icon="list-check">
    Include at least 6-12 products in your pool so customers feel they have real choice. With variant selection enabled, even fewer products can offer substantial variety (e.g., 6 products with 3 variants each = 18 options).
  </Accordion>

  <Accordion title="Enable variant selection for product variety" icon="palette">
    If your products have multiple variants (flavors, colors, sizes), enable **Allow Variants Selection**. This lets customers:

    * Choose 3 different flavors of the same tea
    * Mix sizes in a clothing bundle
    * Build a variety pack from a limited product set
  </Accordion>

  <Accordion title="Set realistic min/max limits" icon="hashtag">
    * **Minimum**: High enough to make the discount worthwhile (typically 3-5)
    * **Maximum**: Prevents oversized orders that might affect profitability (typically 10-20)
    * Show the range clearly: "Build Your Box (3-6 items)" in the title
  </Accordion>

  <Accordion title="Use tiered discounts to encourage larger orders" icon="chart-line">
    Create compelling tiers:

    * 3 items: 10% off (entry tier)
    * 5 items: 15% off (sweet spot)
    * 8+ items: 20% off (bulk tier)

    Each tier should feel like a meaningful upgrade.
  </Accordion>

  <Accordion title="Link to the Build-a-Box page" icon="link">
    The standalone Build-a-Box page (`/apps/bundles?bundle=ID`) provides a better experience than the on-page widget for complex bundles:

    * Add a "Build Your Box" button in your navigation
    * Feature it on your homepage or collection pages
    * Use it in email campaigns
    * Share the link on social media
  </Accordion>

  <Accordion title="Keep products similar in value" icon="scale-balanced">
    If products have widely different prices, use percentage discounts rather than fixed pricing. This prevents customers from gaming the system by choosing only expensive items.
  </Accordion>

  <Accordion title="Customize text for your audience" icon="language">
    Use the translatable text fields to:

    * Match your brand voice
    * Translate for international customers
    * Create urgency ("Only {n} more to unlock 20% off!")
    * Provide helpful guidance
  </Accordion>

  <Accordion title="Group similar products" icon="layer-group">
    Mix & Match works best within a category (all teas, all protein bars, all candles) rather than across disparate categories. Customers understand the value better when products are related.
  </Accordion>
</AccordionGroup>

## Example Mix & Match Bundles

<CardGroup cols={2}>
  <Card title="Food & Beverage" icon="mug-hot">
    **Coffee Sampler**: Choose any 4 coffee bags from our collection for \$40
  </Card>

  <Card title="Fashion" icon="shirt">
    **T-Shirt Bundle**: Pick any 5 basic tees for $50 (usually $15 each)
  </Card>

  <Card title="Beauty" icon="soap">
    **Bath Bomb Variety Pack**: Select 6 bath bombs from 15 scents for \$30
  </Card>

  <Card title="Snacks" icon="cookie">
    **Protein Bar Mix**: Build your own 10-pack, choose from 12 flavors, 15% off
  </Card>
</CardGroup>

## Pricing strategies

### Fixed bundle price (recommended for similar-priced products)

**Scenario**: All teas cost $8-$10 each

* **Offer**: Choose any 5 for $35 (regular price would be $40-\$50)
* **Benefit**: Simple, clear value proposition
* **Customer behavior**: More likely to explore different options

### Percentage discount (recommended for varied pricing)

**Scenario**: Products range from $5 to $20

* **Offer**: Choose any 6 items, get 20% off
* **Benefit**: Fair discount regardless of selection
* **Customer behavior**: May gravitate toward higher-priced items (which is fine)

## Troubleshooting

**Widget not showing products**:

* Verify bundle status is **Active**
* Check that product pool has at least 2 products
* Ensure products have available inventory
* Check browser console for JavaScript errors

**Variant dropdown not appearing**:

* Confirm **Allow Variants Selection** is enabled in bundle settings
* Product must have multiple variants (not just the default)
* Dropdown only appears when at least one unit is selected

**Customers can't add to cart**:

* Check that selected quantity is between min/max limits
* Verify at least one offer tier is configured
* Ensure selected quantity meets the minimum for at least one offer

**Build-a-Box page not loading**:

* Verify the bundle ID in the URL is correct (`/apps/bundles?bundle=123`)
* Check that the app proxy is configured in Shopify admin
* Bundle must be **Active** status

**Discount not applying at checkout**:

* Confirm Shopify Functions extension is deployed
* Check that bundle products have the `appfox_bundle` property in cart
* Verify offer conditions match the cart quantity
* Test with a fresh cart (clear existing items)

**Text not translating**:

* Custom text fields override defaults; set them per bundle if needed
* Check Prisma migration ran successfully to add text fields
* Verify bundle data includes custom text fields

<Tip>Build-a-Box bundles have the highest engagement and average order value because customers love the customization. Use analytics to track which products and variants are most frequently chosen to optimize your product mix and pricing tiers.</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.