Build bundles with your own storefront UI

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 the three most common 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.

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.

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 are mandatory

If the required _appstle-* line attributes are missing, the Function cannot recognize the line and no discount is applied.

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

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.

Create and activate the bundle in the Appstle admin

Configure the bundle (products, pricing, tiers) in the Appstle dashboard and set its status to Active. 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.

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:

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.

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.

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 Storefront API cartLinesAdd mutation (fully headless), attaching the bundle line attributes.

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. The first option should cover almost every storefront.

Shop metafield (recommended)
Shopify Storefront API (fully headless)
Appstle App Proxy (last resort)
Appstle Admin API (backend only)

Appstle publishes all active bundle rules to the shop metafield appstle_bundles.bundle_rules. This is the same data that drives Appstle’s own widgets (exposed there as window._ABConfig.bundle_rules), and it contains every rule type — fixed pricing, dynamic pricing, and volume discount.On a Shopify theme, read it directly in Liquid — no network call to anyone:

{% assign bundle_rules = shop.metafields.appstle_bundles.bundle_rules.value %}
<script>
  window.MY_BUNDLE_RULES = {{ bundle_rules | json }};
</script>

Then filter to the bundle you want by bundleType and uniqueRef:

const rules = window.MY_BUNDLE_RULES || [];
const volumeBundles = rules.filter(r => r.bundleType === 'VOLUME_DISCOUNT' && r.status === 'ACTIVE');

Several rule fields are themselves JSON-encoded strings inside the metafield (for example tieredDiscount, products, variants). Parse them with JSON.parse(...) before use — exactly as Appstle’s own widget does.

On a non-theme stack (Hydrogen, a custom frontend), fetch the same shop metafield through Shopify’s Storefront API rather than calling Appstle:

query BundleRules {
  shop {
    metafield(namespace: "appstle_bundles", key: "bundle_rules") {
      value
    }
  }
}

value is a JSON string — parse it into the rules array. Hydrate product titles, images, and prices with Shopify’s Storefront API as usual. If the metafield is not exposed to the Storefront API for your store, read it server-side via the Shopify Admin API and cache it.

Appstle exposes build-a-box configuration through your store’s Shopify App Proxy. Use these only when you need server-parsed product hydration that you cannot get from Shopify directly, and cache the responses — they are not meant for per-request, storefront-scale traffic.

Endpoint (via App Proxy)	Returns
`GET /bundles/bb/api/build-a-box/by-token/{token}`	A single bundle rule, where `{token}` is the rule’s `uniqueRef`.
`GET /bundles/bb/api/build-a-box/get-bundle/{handle}`	The rule plus a parsed `products` array (`productId`, `variantId`, `name`, `productHandle`, `imageSrc`, `price`, `minQuantity`, `maxQuantity`, `mandatory`, …) ready to render.
`GET /bundles/bb/api/build-a-box/single-product`	All active fixed-pricing build-a-box rules for the shop.

For server-side use cases — ERP sync, reporting, internal tooling — read rules with the X-API-Key Admin API. This requires a secret key and must never run in a browser or storefront context. See Authentication.

curl -X GET \
  "https://bundles-admin.appstle.com/api/external/bundle-rules?shop=${SHOP}&status.equals=ACTIVE" \
  -H "X-API-Key: ${APPSTLE_API_KEY}"

Bundle type reference

Each Appstle bundle type maps to a bundleType value in the rules data. These three are supported for headless storefronts:

Merchant label	`bundleType`	`bundleSubType`
Fixed pricing bundle	`SINGLE_PRODUCT_BUILD_A_BOX`	`FIXED_BUNDLE`
Dynamic pricing bundle	`CLASSIC_BUILD_A_BOX`	—
Volume discount bundle	`VOLUME_DISCOUNT`	—

Other values exist in the bundleType enum (for example DISCOUNTED_PRICING, BUY_X_GET_Y, SECTIONED_BUNDLE, COMBO_BUNDLE). This documentation covers the three 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:

Field	Type	Used by	Meaning
`uniqueRef`	string	all	Stable reference for the bundle. You attach this to every cart line as `_appstle-bb-id`.
`discountType`	enum	dynamic, volume	One of `PERCENTAGE`, `FIXED_AMOUNT`, `FIXED_BUNDLE_AMOUNT`, `TIERED_DISCOUNT`, `NO_DISCOUNT`, `FREE_GIFT`.
`discountValue`	number	dynamic	The percentage (e.g. `15` = 15%) or fixed amount, depending on `discountType`.
`price`	number	fixed	The fixed total price the customer pays for the bundle.
`tieredDiscount`	string (JSON)	volume	JSON array of tier objects (see the Volume discount guide).
`minProductCount` / `maxProductCount`	integer	dynamic, fixed	Min / max number of items the customer must select.
`minOrderAmount` / `maxOrderAmount`	number	dynamic	Min / max selection value required for the discount to apply.
`products` / `variants`	string (JSON)	all	Eligible products and variants configured for the bundle.
`status`	string	all	The bundle is only live when `ACTIVE`.

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 the Storefront API they are line attributes. Both surface to the Function as cart-line attributes.

Attribute key	Required	Value	Purpose
`_appstle-bb-id`	Yes	The rule’s `uniqueRef`	Links the line to a specific bundle so the Function knows which rule to apply.
`_appstle_bundles_type`	Yes	The `bundleType` value (e.g. `VOLUME_DISCOUNT`)	Tells the Function which discount logic to run.
`__appstle-bb-name`	Recommended	The bundle’s `name`	Human-readable label shown in cart/order line items.
`_appstle_bundle_combo_id`	Volume only (tier restriction)	The selected tier’s identifier	Pins the line to a specific tier when tier restriction is enabled.
`_appstle-bb-child`	Fixed only (child items)	`"true"`	Marks component lines added alongside the parent in certain inventory modes.

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)

await fetch(`${Shopify.routes.root}cart/add.js`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    items: [
      {
        id: variantId,          // numeric Shopify variant ID
        quantity: 2,
        properties: {
          '_appstle-bb-id': bundle.uniqueRef,
          '_appstle_bundles_type': bundle.bundleType,
          '__appstle-bb-name': bundle.name,
        },
      },
    ],
  }),
});

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

mutation AddBundleLines($cartId: ID!) {
  cartLinesAdd(
    cartId: $cartId
    lines: [
      {
        merchandiseId: "gid://shopify/ProductVariant/123456789"
        quantity: 2
        attributes: [
          { key: "_appstle-bb-id", value: "your-bundle-uniqueRef" }
          { key: "_appstle_bundles_type", value: "VOLUME_DISCOUNT" }
          { key: "__appstle-bb-name", value: "Summer Skincare Set" }
        ]
      }
    ]
  ) {
    cart { id }
    userErrors { field message }
  }
}

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, and even exposes a window._ABConfig.getProductDiscountedPricing(...) helper on theme storefronts.) The formula differs per type — see each guide:

Fixed pricing — savings = sum of line prices − price.
Dynamic pricing — percentage or fixed amount off the eligible subtotal.
Volume discount — the best-matching tier’s discount.

All monetary values in the Shopify cart are expressed in the minor unit (cents). A total_price of 5000 means $50.00. Account for this when computing previews.

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.

Authentication

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

Fixed pricing bundle

Dynamic pricing bundle

Volume discount bundle

​Design principle: lean on Shopify, not on Appstle

No discount codes

The Function is authoritative

Attributes are mandatory

​Prerequisites

​The integration model

​Reading bundle configuration

​Bundle type reference

​Discount fields on a rule

​Required cart line attributes

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

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

​Previewing the discount

​Next steps

Fixed pricing bundle guide

Dynamic pricing bundle guide

Volume discount bundle guide

Authentication

Design principle: lean on Shopify, not on Appstle

Prerequisites

The integration model

Reading bundle configuration

Bundle type reference

Discount fields on a rule

Required cart line attributes

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

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

Previewing the discount

Next steps