EzyStudio Alfo - Discount Functions

Bundle Builder

Overview

Bundle Builder is a storefront bundle wizard. It renders as a theme block on your Online Store 2.0 theme and walks shoppers through assembling a complete bundle one component at a time. When they finish, every item is added to the cart at once and the bundle discount is applied automatically.

Unlike a standard product page, the Bundle Builder enforces your bundle’s structure: the shopper can only continue once each required component is filled, and the savings display updates live as they make their picks.

Plan requirement: Enterprise only. A Bundle Builder block always pairs with a Bundle Discount configured in the Alfo app.

How It Relates to Bundle Discount

The Bundle Builder is the storefront experience that helps shoppers build a qualifying bundle. The Bundle Discount is the cart-time discount function that applies the savings at checkout. They work together across three layers:

  1. The Bundle Discount defines which products belong to which bundle component, and what discount applies once a complete bundle is in the cart.
  2. The Bundle Builder theme block renders the picker UI — one step per component, with product filtering that matches your discount rule.
  3. A dedicated cart-transform function merges the resulting lines into a bundle group and applies your configured discount type (percentage, fixed amount, or fixed price) before the buyer sees the total.

Pricing is never computed client-side. All discount parameters are stored server-side and looked up by a bundle handle, so nothing in the storefront page can change the final price.

Setup Flow

  1. Create a Bundle discount. In the Alfo admin, create an Enterprise Bundle Discount with at least one rule group and the component filters that describe your bundle (for example, 1 top, 1 bottom, 1 accessory).
  2. Enable Cart Transform on the discount. Toggle the “Enable Cart Transform” option on the Bundle discount. This publishes the pricing catalog and creates the storefront metaobject the theme block uses. If you have multiple bundles configured already, use the Sync all bundles button on the app Settings page to rebuild every catalog entry at once.
  3. Add the theme block to your storefront. Open your theme in the Shopify theme editor and drop the Bundle Builder block onto a page, product template, or custom section.
  4. Set the block’s bundle handle. In the block’s settings panel, set the Bundle handle to the auto-generated handle shown on the Bundle discount’s detail page. This tells the block which bundle to render.

Once the block is configured, publish your theme. Shoppers visiting the page will see the multi-step picker.

Theme Block Settings

The Bundle Builder block is configured entirely through Shopify’s theme editor. Every setting is visible in the block’s side panel:

SettingDescription
Bundle handleThe lookup key that tells the block which bundle to render. Copy this from the Bundle discount’s detail page.
Intro headline / textCopy shown on the first step before the shopper begins picking.
Summary headline / textCopy shown on the final summary step before “Add bundle to cart”.
Progress bar styleChoose between dots, numbered steps, or a progress line.
Savings badge toggleShow or hide the live savings display on each step.
Color tokensMatch the block’s colors to your theme’s accent, background, and text colors.

All bundle logic (required components, filters, quantities, discount value) is read from the Bundle discount you configured in the app — the theme block only handles presentation.

Storefront Behavior

The shopper flow proceeds in discrete steps:

  1. Intro step — Shows the bundle’s purpose, total savings preview, and a “Start building” CTA.
  2. Component steps — One per component in your discount. The shopper sees only products matching that component’s filter and picks from them (with variant selection where applicable).
  3. Summary step — Lists every pick, shows the original total, the bundle total, and the savings amount. A single “Add bundle to cart” CTA adds every item at once.

Two JavaScript events are dispatched for theme integrations that need to react to bundle activity:

  • alfo:bundle:added — Fired after a bundle is successfully added to the cart. Payload includes the bundle handle, session ID, and total savings.
  • alfo:bundle:error — Fired when an item fails to add (for example, an out-of-stock variant). Payload includes the error reason.

You can listen for these from your theme’s custom JavaScript if you want to trigger confetti, analytics events, or cross-sells.

Pricing and Trust Model

Pricing is never read from the storefront page. When the shopper adds their bundle to the cart, each line carries attribution that identifies the bundle — but the discount value, type, and scope are looked up server-side from a catalog keyed by the bundle handle. Tampering with anything in the page, including line properties or the cart token, can’t change the final price.

If the handle isn’t found in the catalog, or if a selected variant isn’t on the bundle’s allowed list, the cart-transform function silently declines to merge or discount the lines. The shopper sees full, un-discounted prices rather than unexpected behavior.

Limitations

  • Enterprise only — The Bundle Builder requires the Bundle discount type, which is only available on the Enterprise plan.
  • Online Store 2.0 themes — The block is a theme app extension. Your theme must support app blocks (every theme in Shopify’s Theme Store built in the last few years does).
  • One bundle per block — Each Bundle Builder block renders a single bundle. To showcase multiple bundles, drop multiple blocks onto the page or template.

Analytics

Every bundle added to cart that results in a completed order is tracked and surfaced in the Analytics Dashboard. You’ll see revenue, accepts, top-performing bundles, and daily trends — all broken out by bundle handle.

Next Steps