What is a bundle?
A bundle is a subscription where the customer pays a fixed price for a box of N items and assembles the box themselves from a curated set of products you’ve made eligible. You define the bundle once (its name, the box sizes you sell with a price for each, and the eligible products) and customers fill it from the product page. At checkout, a discount function brings every item down to the same per-item share, so whatever combination the customer picks adds up to the price of the box size they chose.When to use a bundle
Curated boxes
Snack boxes, beauty boxes, coffee samplers: anything where the customer
chooses N items from a larger catalog.
Build-your-own kits
Supplement stacks, meal kits, pet-food selections. The customer mixes and
matches what they want.
Tiered "pick N" plans
“Pick 3 for €30 / month” or “Pick 5 for €45 / month”. Sell the same catalog
at several sizes by adding a tier per size to one bundle template.
Rent several items
A customer rents three items as one box and sends one back. With
Returned items stop billing on, its share comes off the charge.
Use a regular subscription plan
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
- You create a bundle template in the app: a name, one or more box sizes with a price each, the eligible products, and what a return does to the price.
- Each eligible product shows a Subscription bundle card on its product page with an “Add to bundle” button.
- The customer adds items to the cart until the count matches a size you priced (for example 3 / 3).
- At checkout, a Shopify discount function discounts the bundle’s cart lines so the bundle subtotal matches that size’s price.
- After the order, circuly creates the subscription contract and a bundle instance tied to that customer. They can swap items, return an item, or fill an empty slot from the bundle manage page on your storefront.
Prerequisites
Before creating a bundle, make sure: - The circuly theme extension is
installed in your active theme. See Theme Extension
Setup. - The products you want to include
already exist in Shopify. - Each eligible variant is priced at at least the
per-item share of every size (the size’s price divided by its item count).
The discount function can only discount lines down, never raise them. If
the items a customer picks add up to less than the box price, they pay that
lower amount, not the box price. The bundle form warns you when an eligible
product is priced below the per-item share.
Create a bundle
1
Open Bundles in the app
In Shopify Admin, open circuly Rental & Subscriptions → Bundles, switch to the Bundle templates tab, then click Create a bundle template.
2
Fill in the basics
- 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
Set your sizes and prices
Under Bundle sizes and prices, add one tier per box size you sell: Items (the exact count) and Box price. The card shows the resulting price per item next to each tier. Click Add another tier for the next size, up to 10 tiers.Customers can only check out when their box matches a tier exactly. A box of 4 items on a 3 / 5 ladder gets no discount and cannot be checked out from the card.
4
Decide what happens when an item comes back
Under Returns, the Returned items stop billing checkbox decides what a return does to the price. It is off by default and applies to returns closed after you save; boxes that were already repriced keep their new price either way.
- Off: a returned item frees its slot, but the customer keeps paying the full box price until they fill the slot again from the manage page.
- On: when the return is closed, the item is taken off the subscription and its share of the price comes off the recurring charge. The share is the price of the size they bought divided by its item count, rounded down to the cent, so a second return takes off the same amount. The invoice then reads, for example,
Snack box - 3 of 4 items. Filling the slot again adds the item back at the same per-item share.
5
Pick the eligible products
Under Eligible products, click Assign products and pick every product customers may add to this bundle. You need at least as many products as your largest tier, and the form tells you how many are still missing. Customers always choose from this list.
6
Review the summary and save
The summary on the right lists each tier with its per-item price (the cheapest per item is marked Best value), the number of eligible products, the largest box, and a checklist of what is still missing before you can save. The preview fills the slots with the thumbnails of the products you assigned, so you see the box the way a customer will. When you’re happy, click Save in the bar at the top.
Migrate bundle data
The bundle card on a product page is driven by a small piece of data circuly stores on each eligible product. If that data goes missing (for example after a theme or app reinstall), the card disappears from product pages even though the template still exists. On the Bundle templates tab, click Migrate bundle data to rewrite it for every bundle. It also brings back bundles that exist in Shopify but are missing from the list. It is safe to run as often as you like.Storefront experience
Once the bundle is created, every eligible product shows a Subscription bundle card on its product page, rendered inside the Unified purchase selector block. The card has a coloured header with the bundle name (set the colour with Bundle primary color in the block settings), a progress bar with a marker per size you priced, a grid of thumbnails of the items already in the box with empty slots up to the next size, and an Add to bundle button. A single-size bundle also shows the monthly price in the header; a multi-size bundle shows each size’s price on the progress bar.
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 to add it.
Bundle manage page
After the order is placed, the customer can open Manage your bundle from any eligible product page or from the Bundle progress cart block to see what is in the box and change it. This is a circuly-rendered page served at/apps/api/bundle/<id> on your storefront and it inherits your theme’s layout. Changes apply on the next delivery.
Each slot is a card with the product image and name and up to three actions:
While a return is open, the slot shows Return in progress and hides both Swap and the return button.
Bundles are managed on the storefront. In the Shopify customer account
the bundle subscription is listed and can only be cancelled; swapping,
returning and refilling happen on the bundle manage page.
Returns from a bundle
A customer returns one item at a time from the bundle manage page. You can also start the return yourself from the order in Shopify Admin; both paths behave the same from here on.- Request. The customer clicks Return this item. circuly opens a return request on the original order in Shopify, and the slot shows Return in progress on the manage page. Nothing changes on the subscription yet.
- Approve. You approve the return under Orders → the order → Returns, exactly as for any other Shopify return. circuly does not create a shipping label for bundle items; use your usual returns process.
- Close. When the item is back and you close the return in Shopify, circuly frees the slot. What happens to the price depends on the template’s Returned items stop billing setting:
- Off: the price stays the same. The customer can fill the slot again from the manage page.
- On: the item is removed from the subscription and the recurring charge drops by the per-item share. The Price column in Active bundles and the invoice line reflect the new amount, for example
Snack box - 3 of 4 items.
The return window counts from the day that item was fulfilled, and an item
that isn’t fulfilled yet cannot be returned. Returning several units of the
same product frees that many slots. A refund on the order also frees the
slot, but it never changes the price, even with Returned items stop
billing on.
Monitor active bundles
In Shopify Admin, open circuly Rental & Subscriptions → Bundles. The Active bundles tab lists every bundle subscription customers have assembled. The index shows the following columns:
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.Limitations
- Storefront-only management. Swapping, returning and refilling happen on the bundle manage page. In the Shopify customer account the bundle subscription can only be cancelled.
- Size and price edits don’t propagate to existing bundles. Changing a template’s sizes or prices only affects new bundles assembled after the edit. Active subscriptions keep their original terms. The eligible product list does apply immediately, on the storefront and in the manage page.
- No return labels. circuly opens the return in Shopify but does not create a shipping label for a bundle item. Handle the shipment with your usual returns process.
- 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.