- 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.
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.
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.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.- Shop metafield
- Shopify Admin API
- App Proxy
- Appstle Admin API
Appstle publishes all active bundle rules to the shop metafield When a store’s rules are too large for one metafield (more than 2,000,000 characters of JSON), Appstle splits them between
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: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 abundleType 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-itemproperties; 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.
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 exposeswindow._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.