Product Bundling & Mix-and-Match

Free — GPL coresize Lplanned, not built

Generated from docs/plan/core/product-bundling-mix-and-match/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Core free module that lets merchants create product bundles (fixed sets of items) and mix-and-match offers (e.g., ‘pick any 3 from these 5 items for €50’). Bundles have their own SKU, pricing, and inventory. Storefront renders bundle builder UI; checkout calculates bundled pricing and ensures item constraints are satisfied before allowing purchase.

The problem

A retailer’s average order value drops because customers buy single items. They want to suggest ‘3-pack of socks for €20 (save €5)’ or ‘pick any 2 scarves from our collection for €30’ but lack a system to enforce bundle pricing or inventory allocation. Without bundling, merchants lose 15–20% of potential margin.

What it does

• Bundle type 1 (fixed): ‘iPhone + 2 AirPods = bundle SKU BUNDLE001’ with fixed items and bundle price
• Bundle type 2 (mix-and-match): ‘pick 3 items from [itemA, itemB, itemC, itemD, itemE] for €50 total’
• Bundle creation in admin: select items, quantities, and bundle price (lower than sum of items)
• Bundle inventory: bundles have their own stock (e.g., 10 bundles available); when bundle is purchased, item inventory is decremented (or merchants choose not to decrement)
• Storefront bundle builder: if mix-and-match, render 5 items, let customer choose 3, show total price dynamically
• Checkout validation: ensure customer selected correct number of items before allowing purchase
• Discount display: ‘save €5 with this bundle’ shown on bundle card and in checkout
• Analytics: show bundle popularity and margin contribution

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• AI frequently-bought-together recommendations (see product-bundling-mix-and-match paid module variant for AI)
• Volume-based bundle pricing (see quantity-discounts-tiered-volume-pricing)
• Subscription bundles (see a future subscriptions module)

Data model

Add product_bundles table: { id, shop_id, bundle_name, bundle_sku, bundle_price_minor_units, bundle_type (‘fixed’ or ‘mix_and_match’), bundle_inventory, items_in_bundle (JSON: [{product_id, variant_id, quantity_required}, …]), discount_amount_minor_units (calculated)}. Schema migration: new table.

API

• POST /admin/products/bundles — create bundle with items and price
• PUT /admin/products/bundles/:id — edit bundle
• GET /products/bundles/:id — read bundle details and items
• POST /checkout/validate-bundle — { bundle_id, selected_items } → returns { valid: true/false, error_message }
• GET /admin/analytics/bundles — show bundle sales, margin, and popularity

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Add ‘Bundles’ tab in Products section. List bundles with SKU, price, discount amount, and stock. Click to create/edit: form with bundle name, type selector (fixed/mix-and-match), item selector (add items, set quantities), bundle price input. Show estimated savings. Stock counter per bundle.

The seam — why this is core

Core owns bundle structure and mix-and-match logic. Merchants can manually create bundles. Paid AI module owns frequently-bought-together algorithm (analyzes past orders, suggests optimal bundles).

Core owns bundle primitive in product schema and checkout offer rendering; paid module owns AI frequently-bought-together recommendations

Dependencies

• Product system (bundles must reference products)
• Checkout flow (to validate bundle constraints)
• Inventory system (to track bundle stock)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Bundle ‘iPhone Bundle’ includes 1 iPhone + 2 AirPods; bundle price = €900, sum of items = €950, discount shown = €50
• Mix-and-match bundle requires customer to select 3 items from 5 options; selecting 2 shows error ‘please select 3 items’
• Checkout calculates bundle price €50 when 3 items are selected, not sum of individual prices
• Bundle inventory tracks separately: if 10 bundles available and customer buys 1, bundles_remaining = 9
• Admin can view bundle popularity: ‘50 bundles sold this month, average margin €20/bundle’

Risks

If bundle inventory is not decremented when purchased, over-selling occurs (always check inventory before allowing purchase). If mix-and-match selected items are not stored with order (customer selected 2x itemA + 1x itemB but only ‘bundle 3-pack’ is recorded), order fulfillment is ambiguous.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.