> ## Documentation Index
> Fetch the complete documentation index at: https://app.docs.circuly.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Bundles
> Sell a curated set of products as a single fixed-price subscription — customers pick the items they want.
## What is a bundle?
A **bundle** is a subscription where the customer pays a single fixed price and assembles their order from a curated set of products you've made eligible. You define the bundle once — its name, fixed price, and how many items it contains — and customers fill it themselves from the product page.
At checkout, a discount function spreads the fixed price evenly across the items the customer picked, so whatever combination they choose adds up to the same monthly total.
***
## When to use a bundle
Snack boxes, beauty boxes, coffee samplers — anything where the customer chooses N items from a larger catalog.
Supplement stacks, meal kits, pet-food selections — the customer mixes and matches what they want.
"Pick 3 for €30 / month" or "Pick 5 for €45 / month" — sell the same catalog at different bundle sizes by creating a bundle template per size.
Discovery boxes where the customer picks favourites each renewal rather than receiving a pre-set selection.
Use a regular [subscription plan](/docs/mintlify/create-subscription-plans) when the buyer subscribes to **one specific product**. Use a bundle when the buyer subscribes to **a curated selection** they choose themselves.
***
## How bundles work
1. You create a **bundle template** in the app: name, capacity (e.g. 3 items), fixed monthly price, and the products that are eligible to be picked.
2. Each eligible product shows a **Subscription bundle** card on its product page with an "Add to bundle" button.
3. The customer adds items to the cart until the bundle is full (e.g. 3 / 3).
4. At checkout, a Shopify discount function evenly discounts the bundle's cart lines so the bundle subtotal matches the fixed price you configured.
5. After the order, Circuly creates the subscription contract and a **bundle instance** tied to that customer. They can swap items, manage the bundle, or reset it from the storefront.
***
## Prerequisites
Before creating a bundle, make sure:
* The Circuly theme extension is installed in your active theme — see [Theme Extension Setup](/docs/mintlify/theme-extension).
* The products you want to include already exist in Shopify.
* Each eligible variant is priced at **at least the per-item share of the bundle price**. The discount function can only **discount lines down**, never raise them. If the variant prices add up to less than the bundle price, the customer will be charged the higher variant price instead of the bundle price.
***
## Create a bundle
In Shopify Admin, open **Circuly Rental & Subscriptions** → **Bundles** → **Bundle templates**, then click **Create a bundle**.
* **Bundle name (buyer-facing)** — shown to the customer at checkout and on the manage page. Example: `Snack box`.
* **Internal code** — merchant-facing identifier you'll see in the admin and exports. Example: `SNACK_BOX_3`.
* **Items per bundle** — how many items the customer picks per bundle. Example: `3`.
* **Fixed monthly price** — the total the customer pays each renewal, in your shop currency. Example: `30.00`.
Under **Eligible products**, search for and select every product that customers should be able to add to this bundle. The "Items per bundle" value is the maximum they'll pick — they always choose from this list.
The summary on the right shows the per-item share (`Fixed price / Items per bundle`) so you can sanity-check pricing against your variant prices. When you're happy, click **Create bundle template** in the top right.
You can edit a bundle template later — name, price, capacity, and eligible products are all editable. Any **active** bundles already built from the template keep their original settings; only new bundles assembled after the edit will use the new values. Templates with active subscriptions cannot be deleted.
***
## Storefront experience
Once the bundle is created, every eligible product shows a **Subscription bundle** card on its product page (rendered inside the existing Unified purchase selector widget). The card has a pink header with the bundle name and monthly price, a progress bar showing `N / capacity`, and an **Add to bundle** CTA.
| State | What the customer sees |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Empty** | "Add to bundle" button. Counter shows `0 / capacity`. |
| **In progress** | Progress bar fills up. Reset button appears so they can start over. |
| **Full** | "Check out" button replaces "Add to bundle". The progress bar is full. |
| **Active subscription** | "Your active subscription" pill appears below with a Manage button linking to the bundle manage page. |
| **Active + eligible variant** | When the customer's existing bundle is full and they land on a product that's eligible, a **Replace a bundle item with this product** picker appears so they can swap a slot without going through the cart. |
A second block — **Bundle progress** — is available for the cart page or cart drawer. It surfaces the same counter inside the cart so customers see how many slots are left while they shop. See [Theme Extension Setup → Bundle progress block](/docs/mintlify/theme-extension#bundle-progress-block) to add it.
### Bundle manage page
After the order is placed, the customer can open `Manage your bundle` from the product page card (or from their order confirmation) to view current items, swap items, or reset the bundle. This is a Circuly-rendered page served at `/apps/api/bundle/` on your storefront — it inherits your theme's layout.
Bundles are managed on the **storefront only**. Bundle controls do not appear in the Shopify Customer Account UI today — buyers reach their bundle via the product page CTA or the link in their order confirmation.
***
## Monitor active bundles
In Shopify Admin, open **Circuly Rental & Subscriptions** → **Bundles** → **Active bundles** to see every bundle subscription customers have assembled.
The index shows the following columns:
| Column | What it means |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| **Bundle** | The buyer-facing bundle name and instance ID. |
| **Template** | Link back to the bundle template the customer assembled from. |
| **Customer** | Shopify customer the bundle belongs to. |
| **Order** | Original Shopify order that created the bundle. |
| **Slots** | Filled slots vs capacity, e.g. `3 / 3`. |
| **Status** | `Active` (live subscription), `Building` (cart in progress, not yet checked out), or `Cancelled`. |
| **Next billing** | Next renewal date for the underlying subscription contract. |
| **Price** | Fixed bundle price for this instance. |
Use the tabs at the top of the index to filter by status.
***
## Pricing details
The bundle price is enforced by a Shopify Function discount that runs on the cart and at checkout.
| Variant total vs bundle price | What the customer pays |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Variant prices **sum to more** than the bundle price | Function discounts the lines evenly so the bundle subtotal equals your configured fixed price. |
| Variant prices **sum to less** than the bundle price | Lines stay at their variant price — the bundle subtotal will be **higher** than your fixed price. Shopify cannot raise a line above its variant price. |
| One of the lines has a selling plan attached | Discount is applied as a fixed-amount cart-level adjustment. Per-line repricing isn't allowed by Shopify when a selling plan is attached, so the discount surfaces on the order rather than the line. |
Always set your variant prices so the eligible items sum to **at least** the bundle price. Otherwise customers will be charged more than the bundle price you advertised.
***
## Limitations
* **Storefront-only management.** Bundles are not surfaced in the Shopify Customer Account UI today. The PDP card and the bundle manage page are the buyer-facing controls.
* **Edits don't propagate to existing bundles.** Changing a template's price, capacity, or eligible products only affects new bundles assembled after the edit. Active subscriptions keep their original terms.
* **Discount function must be active.** Bundle pricing is enforced by Circuly's discount function. If it's been disabled under **Shopify Admin → Discounts**, bundle lines will charge at full variant price. Re-enable the Circuly bundle discount to restore bundle pricing.
***
## Troubleshooting
| Problem | What to check |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bundle line price is wrong at checkout | Variant prices must sum to **at least** the bundle price. Confirm the Circuly bundle discount is enabled under **Shopify Admin → Discounts**. |
| Storefront card doesn't appear on a product | The product isn't on the bundle's eligible list, or the **Unified purchase selector** block isn't placed on the product template. See [Theme Extension Setup](/docs/mintlify/theme-extension). |
| Customer can't open the manage page | The manage link requires the customer to be logged in. They can sign in from their order confirmation email and retry. |
| Bundle stays in **Building** | The cart was never checked out, or the order webhook hasn't arrived yet. Building bundles are kept for traceability — they don't bill anything. |
| Can't delete a bundle template | The template still has active subscriptions. Cancel them from **Active bundles** first, then retry. |