Skip to main content
Many merchants love how Appstle Bundles calculates and applies discounts but want to design the customer-facing experience themselves so it matches their theme. Appstle fully supports this headless (or bring-your-own-UI) model for five bundle types:
  • Fixed pricing bundle — a set of products sold for one fixed total price.
  • Dynamic pricing bundle — a build-your-own selection with a percentage or fixed-amount discount applied to the running total.
  • Volume discount bundle — tiered “buy more, save more” discounts based on quantity or spend.
  • Combo bundle — a fixed set of products sold together at a per-product discount, one-time or as a subscription.
  • Sectioned bundle — a box split into sections, each with its own minimum and maximum, discounted by tiers or by one percentage or amount off the box, one-time or as a subscription.
The mental model in one sentence: you use the exact same Shopify metafields, cart-line attributes, and discount Functions that Appstle’s own bundle widgets use — the only thing you replace is the UI. Nothing about how the bundle is configured, priced, or discounted changes; you are simply rendering the experience yourself instead of letting Appstle’s widget render it.
This page explains the architecture that makes headless integrations possible. The per-bundle guides then walk through each type end to end.

Fixed pricing bundle

Sell a curated set for one fixed price.

Dynamic pricing bundle

Build-your-own with a percentage or amount discount.

Volume discount bundle

Tiered “buy more, save more” discounts.

Combo bundle

A fixed set of products at a per-product discount.

Sectioned bundle

A box with section limits and tiered savings.

Design principle: lean on Shopify, not on Appstle

Read configuration from Shopify metafields, fetch product data from Shopify’s own APIs, compute previews on the client, and let the discount apply through a Shopify Function. Treat calls to Appstle’s servers as a last resort, and cache them when you do make them. This is exactly how Appstle’s own storefront widgets are built — they read everything from a Shopify metafield and almost never call back to Appstle at render time. Following the same pattern keeps your storefront fast and resilient, and avoids putting storefront-scale traffic on Appstle’s API.
The key idea: you never calculate or apply the final discount yourself. The merchant configures the bundle once in the Appstle admin, and Appstle provisions a Shopify automatic discount backed by a Shopify Function in the store, and publishes the rules to a shop metafield. Your storefront reads the rules from that metafield, renders a selector, and adds the customer’s chosen line items to the cart with a small set of line-item attributes. The Appstle discount Function detects those attributes and applies the savings automatically — in the cart, in checkout, and on the final order. This design has three important consequences:

No discount codes

Discounts are automatic, not code-based. You do not request, generate, or apply a discount code anywhere in the flow.

The Function is authoritative

The Shopify Function decides the final discount at checkout. Any number you show in your UI is a preview — compute it from the same rule fields.

Attributes link lines to bundles

Without the _appstle-* line attributes, the Function can’t tie a line to its bundle, and most bundle types get no discount. See what each bundle type needs.
The legacy PUT /bundles/bb/api/build-a-box/discount/{token} endpoint is deprecated and no longer returns a usable discount — discounting moved entirely to automatic Shopify Functions. Do not build a headless flow around it. Apply the line attributes described below instead.

Prerequisites

1

Install Appstle Bundles and keep it active

The discount Functions and the rules metafield only exist while the app is installed. Uninstalling removes the automatic discounts.
2

Create and activate the bundle in the Appstle admin

Configure the bundle (products, pricing, tiers) in the Appstle dashboard and click Launch offer (for an existing draft, click Turn on). The offer then shows as Live, and its status is ACTIVE in the rules data. This provisions the Shopify automatic discount and publishes the rule to the shop metafield. Bundles are authored in the admin; there is no API to create them.
3

Add the Appstle app block once (themes)

On a Shopify theme, enable the Appstle Bundles app embed/block so the rules metafield is available to your code. You can hide Appstle’s default widget and render your own UI from the same data.

The integration model

Every headless bundle, regardless of type, follows the same shape — and most of it runs against Shopify, not Appstle:
1

Read the rules from the Shopify metafield

Appstle publishes active rules to the appstle_bundles.bundle_rules shop metafield. Read it the Shopify-native way — see Reading bundle configuration. No Appstle server call.
2

Render your own selector with Shopify data

Build UI from the rule fields: list eligible products, enforce the selection limits, and show a running total. Use Shopify’s own product/variant data (Liquid objects or the Storefront API) for titles, images, and prices.
3

Validate the selection, then add to cart

When the selection is valid, add the line items via Shopify’s Ajax Cart API (themes) or the Shopify Storefront API cartLinesAdd mutation (fully headless), attaching the bundle line attributes.
4

Let the discount apply automatically

Appstle’s discount Function reads the attributes and applies the savings in cart and checkout. You do nothing else. Optionally render a discount preview computed on the client from the same rule fields.

Reading bundle configuration

Pick the source closest to Shopify. On a Shopify theme, read the Shop metafield. On a headless stack, read the same metafield on your server with the Shopify Admin API. Use the App Proxy only as a last resort, and the Appstle Admin API only from your backend.
Appstle publishes all active bundle rules to the shop metafield appstle_bundles.bundle_rules. It’s the data behind Appstle’s own widgets, and it contains every rule type, such as fixed pricing, dynamic pricing, volume discount, combo and sectioned bundles. On a theme, the widgets also expose the rules as window._ABConfig.bundle_rules, but on some stores that list is incomplete or empty when the page loads. To read every rule from JavaScript, use await window._ABConfig.loadAllBundleRules(). See JavaScript events and API.On a Shopify theme, read it directly in Liquid — no network call to anyone:
When a store’s rules are too large for one metafield (more than 2,000,000 characters of JSON), Appstle splits them between bundle_rules and appstle_bundles.bundle_rules_extended. The if above adds the second list after the first. On most stores bundle_rules_extended doesn’t exist, and the if skips it.Then filter to the bundle you want by bundleType and uniqueRef:
Several rule fields are themselves JSON-encoded strings inside the metafield (for example tieredDiscount, products, variants, singleProductSettings and settings). Parse them with JSON.parse(...) before use — exactly as Appstle’s own widget does.

Bundle type reference

Each Appstle bundle type maps to a bundleType value in the rules data. These five bundle types have a guide for headless storefronts. Fixed pricing has two rows, because the offer can sit on a product page or have its own page:
Other values exist in the bundleType enum (for example DISCOUNTED_PRICING and BUY_X_GET_Y). This documentation covers the five types above; the same metafield-plus-attributes model extends to the others.

Discount fields on a rule

The relevant pricing fields on each rule object:

Required cart line attributes

This is the contract between your storefront and Appstle’s discount Function. When you add a bundle line item to the cart, attach these attributes. On a Shopify theme they are passed as line-item properties; through Shopify’s Storefront API they are line attributes. Both surface to the Function as cart-line attributes. Send _appstle-bb-id and _appstle_bundles_type on every bundle line. Which of them the discount needs differs by bundle type (see What each bundle type needs).

What each bundle type needs

The table shows what the discount needs today. Send both attributes on every bundle line anyway: a missing attribute can break other features, such as a bundle’s free shipping or keeping a box’s discount on a subscription. For a fixed pricing bundle’s cart lines, follow Step 3 of the Fixed pricing guide.
Attribute keys are matched exactly, including the leading underscore and the mix of hyphens and underscores (_appstle-bb-id vs. _appstle_bundles_type). Copy them verbatim. Keys beginning with _ are hidden from the customer in standard Shopify cart/checkout UIs.

Adding to cart on a Shopify theme (Ajax Cart API)

Adding to cart on a fully headless stack (Shopify Storefront API)

Previewing the discount

Because the Shopify Function applies the authoritative discount at checkout, any amount you display beforehand is a preview — and you compute it on the client, from the same rule fields, with no server call. (Appstle’s own widget does the same. On a Shopify theme, it also exposes window._ABConfig.getProductDiscountedPricing().) The formula differs per type — see each guide:
  • Fixed pricing — savings = the items’ prices − the box price.
  • Dynamic pricing — percentage or fixed amount off the eligible subtotal.
  • Volume discount — the best-matching tier’s discount.
  • Combo bundle — the sum of each slot’s discount.
  • Sectioned bundle — the reached tier that saves the most, or the rule’s percentage or amount off the box.
Shopify’s /cart.js and Liquid give prices as the amount times 100 in every currency, including currencies without cents: a total_price of 5000 is $50.00 in USD and ¥50 in JPY. The preview code in these guides works in that unit. Shopify’s Storefront API gives amount as a decimal string, such as "29.99", so multiply it by 100 and round it before you use that code.

Next steps

Fixed pricing bundle guide

End-to-end headless walkthrough for fixed-price sets.

Dynamic pricing bundle guide

End-to-end headless walkthrough for build-your-own discounts.

Volume discount bundle guide

End-to-end headless walkthrough for tiered savings.

Combo bundle guide

End-to-end headless walkthrough for fixed sets with per-product discounts.

Sectioned bundle guide

End-to-end headless walkthrough for boxes with section limits and tiered savings, including subscriptions.

JavaScript events and API

The globals, methods and events your theme code can use on a Shopify theme storefront.

Authentication

For backend-only reads — never used from a storefront.