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.
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 theappstle_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:
Each entry of
singleProductSettings describes one box product:
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 ofcollections[](read them with Shopify’s Storefront API). - Keep the number of items in one box between
minQuantityandmaxQuantity, and each item and collection within its own limits. For aFIXEDoffer, use the quantity fromproducts[]for each item. - Don’t offer an item whose variant isn’t available in Shopify (
availableisfalse), unlesstrackInventoryisn’ttrueandsettings.ignoreChildStockWhenUntrackedistrue. 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:
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.
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:
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’sdiscountName, 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.
- The cart has a box line with the same
_appstle-bb-idand with_appstle_bundles_typeset toSINGLE_PRODUCT_BUILD_A_BOX, without_appstle-bb-child, and its variant is thesourceProduct.idof one of the rule’ssingleProductSettingsentries. - The item line has
_appstle_bundles_typeset toSINGLE_PRODUCT_BUILD_A_BOXand_appstle-bb-childset to"true". - When
selectionTypeisFLEXIBLE, 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 betweenminQuantityandmaxQuantity, and each collection incollections[]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’sproducts[]or in one of itscollections[], and its quantity is within that item’s own limits. - When
selectionTypeisFIXED, each item gets the discount for up to itsproducts[].quantitytimes the number of boxes. Extra units are charged their normal price.
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.jsrequest (cartLinesUpdatein Shopify’s Storefront API). - When the customer removes the box, remove its item lines in the same request.
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’ssettings.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-oosset 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 whenhideSubscriptionPurchase 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 as1800 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.