Skip to main content
A fixed pricing bundle sells a set of products as one box for a fixed price. For example, “Any 3 coffees for $36”: the customer pays $36 however much the three coffees cost on their own. This guide shows how to run a fixed pricing bundle from your own storefront UI. You use the same metafield and cart-line properties that Appstle’s built-in widget uses, and only the UI is yours. If you haven’t read the headless overview, start there.

How pricing works

Every fixed pricing offer has a bundle product: a Shopify product that stands for the box. The merchant either lets Appstle create it at the price they set, or picks a product they already have. The customer pays the price of that product’s variant. The items inside the box (the coffees in the example) are what the customer chose. What your cart sends for them depends on the offer’s Track inventory settings, which you read from the rule: If trackInventory is true and inventoryTrackingMode is null, add the box line only: Appstle adds no item lines in that case. With When the order is placed, the order is created with the box line only, so a system that reads new orders (a fulfillment app or an ERP) sees the items only after Appstle’s edit. If Appstle can’t add the items, it tags the order Appstle: bundle items not added. Hold an order with that tag until the items are on it.
inventoryTrackingMode holds a value even when trackInventory is false. Add item lines only when trackInventory is true and inventoryTrackingMode is ADD_CHILD_PRODUCT_ON_CHECKOUT. With any other setting the offer has no discount for item lines, so the customer pays each item’s full price on top of the box.
When you add item lines, the customer still pays the box price: each item line is $0 after the discount. The item lines are there so that Shopify checks each item’s stock at checkout and counts it down when the order is placed, and so that the order lists every item to pack.

Step 1: Read the rule from the metafield

Read the active rules from the appstle_bundles.bundle_rules shop metafield, the Shopify-native source, with no call to Appstle’s servers (see Reading bundle configuration). Keep the fixed pricing bundles by bundleType and status, and parse the two JSON strings each one holds:
The fields you need from each rule: Each entry of singleProductSettings describes one box product:
Hydrate titles, images and prices of the items with Shopify’s own Storefront API or Liquid product objects, using the IDs in products[]. To read exactly what the built-in widget sends for a box, add one on the offer’s own page and open /cart.js.

Step 2: Render your selector

Build whatever UI matches your theme, and drive it from the rule:
  • Show the items in products[], or the products of collections[] (read them with Shopify’s Storefront API).
  • Keep the number of items in one box between minQuantity and maxQuantity, and each item and collection within its own limits. For a FIXED offer, use the quantity from products[] for each item.
  • Don’t offer an item whose variant isn’t available in Shopify (available is false), unless trackInventory isn’t true and settings.ignoreChildStockWhenUntracked is true. In that case the merchant sells the box whatever the items’ stock.
  • Show the box variant’s price from Shopify as the box price, and optionally the saving (see Previewing savings).

Step 3: Add the box to the cart

Send one /cart/add.js request with all the lines of the box, as the built-in widget does. The box line. The variant is sourceProduct.id, and the quantity is the number of boxes. It carries these properties: The item lines (only when trackInventory is true and inventoryTrackingMode is ADD_CHILD_PRODUCT_ON_CHECKOUT). Add one line for each item of the box. The variant is the item’s variant, and the quantity is the item’s quantity in one box times the number of boxes. Each carries:
On a headless storefront, create the cart with cartCreate first, then pass its id as $cartId. The example shows the box line and the first item line: add one more item line for each other item, the same way, and treat the add as done only when userErrors is empty and warnings has no MERCHANDISE_NOT_ENOUGH_STOCK entry. The call needs a Shopify Storefront API access token: see Shopify’s Storefront API documentation.
Never add item lines on their own. The discount applies only while the box line with the same _appstle-bb-id is in the cart, so a customer who removes the box line pays full price for the items.

If Shopify adds less than you asked for

If an item doesn’t have enough stock, /cart/add.js answers 422 with a body like this:
The 422 doesn’t mean nothing was added. Shopify adds every line it can, and cuts a line that asks for more than the stock down to the stock. For example, a request for one box, one Colombia, ten Dark Roast with nine in stock and one Decaf left the box line, one Colombia, one Decaf and nine Dark Roast in the cart, while the message said 3. That box no longer matches the offer, so its items lose the Appstle discount. After a 422, read /cart.js and remove the box’s lines before you retry. Find them by their properties, not by count: in that cart the nine Dark Roast were on two lines. Shopify’s Storefront API reports the same shortfall differently: cartLinesAdd returns an empty userErrors, and warnings holds a MERCHANDISE_NOT_ENOUGH_STOCK entry for each cart line that got less than you asked for. Check warnings after every add. When it holds one, remove the box’s lines with cartLinesRemove before you retry.

Step 4: The discount applies automatically

When the offer adds item lines at checkout, Appstle’s automatic discount takes 100% off each item line, so the cart total is the box price. The discount is labeled with the offer’s discountName, or its name when discountName is empty. It shows in the cart, stays through checkout and is on the order. There is nothing to call. With the other settings there are no item lines to discount: the customer pays the box line’s price. Read the result from /cart.js. This excerpt of a valid box’s response is trimmed to the box line and one of its three item lines. The item line has a discount allocation for its full price, and total_price is the box price. Cart prices are the amount times 100 in every currency, such as 1800 for $18.00.
An item line gets the discount when all of these hold:
  • The cart has a box line with the same _appstle-bb-id and with _appstle_bundles_type set to SINGLE_PRODUCT_BUILD_A_BOX, without _appstle-bb-child, and its variant is the sourceProduct.id of one of the rule’s singleProductSettings entries.
  • The item line has _appstle_bundles_type set to SINGLE_PRODUCT_BUILD_A_BOX and _appstle-bb-child set to "true".
  • When selectionType is FLEXIBLE, all item lines of the offer in the cart are checked together, across every box of the offer. Limits are per box, so multiply them by the number of boxes. The items’ total quantity must be between minQuantity and maxQuantity, and each collection in collections[] must hold between its own limits; if not, no item line of the offer gets the discount. Then each item line gets the discount when its item is in the box’s products[] or in one of its collections[], and its quantity is within that item’s own limits.
  • When selectionType is FIXED, each item gets the discount for up to its products[].quantity times the number of boxes. Extra units are charged their normal price.
These are the cases to design for. Each one was run on the demo store’s guest storefront with the Ajax Cart API, against a FLEXIBLE offer that takes exactly 3 items per box. The box is $36, and the items are $18, $18 and $20. Each row gives the cart total and the total before discounts. The store has other automatic discounts, which apply to item lines when this offer’s discount doesn’t, so some totals are below the full price.

Keep the box together in the cart

The discount reads a box line and its item lines together, so change them together:
  • When the customer changes the number of boxes, set the box line to the new number and each item line to its quantity in one box times the new number, in one /cart/update.js request (cartLinesUpdate in Shopify’s Storefront API).
  • When the customer removes the box, remove its item lines in the same request.
If the item lines don’t follow, a FLEXIBLE box falls under its minimum and its items lose the discount. On a Shopify theme with the Appstle Bundles app embed turned on, Appstle’s cart scripts keep the lines together. On a headless storefront, or a theme without the app embed, your cart code must do it.

If an item runs out

This applies when you add item lines. If an item sells out, Shopify can drop its line when checkout starts, while the box line stays. The rule’s settings.outOfStockChildBehavior says what happens then:
  • REMOVE_ITEM_ONLY (or no value): the customer buys the box at its full price, without the missing item.
  • REMOVE_ENTIRE_BUNDLE: the merchant wants the whole box removed when one of its items is gone. Send _appstle-bb-block-if-child-oos set to "true" on the box line, as Appstle’s widget does. Checkout doesn’t reliably stop a box with a missing item, so check stock before checkout: when an item is gone, remove the whole box from the cart and tell the customer. On a theme with the Appstle Bundles app embed, Appstle’s cart scripts do this. On a headless storefront, your code must do it.

Sell the box on a subscription

Offer a subscription only when hideSubscriptionPurchase isn’t true and appliesOn is SUBSCRIPTION or BOTH. Take the plan from the box variant’s own selling_plan_allocations, and send it as selling_plan on the box line (sellingPlanId in Shopify’s Storefront API). Give an item line the same plan only when the item’s variant has that plan in its own selling_plan_allocations. Otherwise, add the item line without a plan: a line whose plan isn’t attached to its variant makes /cart/add.js answer 422. The item discount follows appliesOn. It applies to item lines with a plan when appliesOn is SUBSCRIPTION or BOTH, and to item lines without a plan when it is ONE_TIME or BOTH.

Previewing savings

To show what the customer saves against buying the items one by one, compare the items’ prices with the box price. Take both from Liquid or Shopify’s Storefront API, so they are current and in the customer’s currency. The code works in the amount times 100, which is how Liquid gives prices in every currency, such as 1800 for $18.00. The Storefront API gives amount as a decimal string, such as "29.99", so multiply it by 100 and round it first:
This is a preview for display only. The price the customer pays is the price of the box line.

Checklist

1

The offer is live in the Appstle admin

Only live offers (status is ACTIVE) are in bundle_rules.
2

The selection respects the limits

Keep each box between minQuantity and maxQuantity, and each item and collection within its own limits (or at the products[] quantities for a FIXED offer). Check it before you add to the cart.
3

The box line is in the cart

The variant is sourceProduct.id, with _appstle-bb-id (the uniqueRef), _appstle_bundles_type and __appstle-bb-variants.
4

The item lines match the offer's Track inventory settings

Add them only when trackInventory is true and inventoryTrackingMode is ADD_CHILD_PRODUCT_ON_CHECKOUT, each with _appstle-bb-child set to "true".
5

The box and its items change together

A new box quantity scales the item lines, and removing the box removes them.
6

Check the cart

Read /cart.js: the total is the box price, and each item line shows a 100% discount.

Next steps

Dynamic pricing bundle

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

Volume discount bundle

Tiered “buy more, save more” discounts.