@zoxllc/shopify-checkout-extensions 0.2.0 → 0.2.1

package/EXAMPLES.md

@@ -360,9 +360,9 @@ export function run(input) {
 
 ---
 
-## Example 11: Multi-Tier Gift with Purchase
+## Example 11: Multi-Tier Gift with Purchase (Cumulative)
 
-**Use Case:** Offer tiered gifts based on cart spend threshold (e.g., spend $75 get Gift A, $100 get Gift B, $250 get Gift C). Only the highest qualifying tier is applied.
+**Use Case:** Offer cumulative tiered gifts based on cart spend threshold. All qualifying tiers are applied (stackTiers: true).
 
 ```json
 {
@@ -405,23 +405,94 @@ export function run(input) {
         "label": "Free Cosmic Drift Daily"
       }
     ],
-    ["meta-exclude-gift"]
+    ["meta-exclude-gift"],
+    true
   ]
 }
 ```
 
-**How It Works:**
+**How It Works (stackTiers: true):**
 - Customer adds items to cart totaling $150
 - Cart subtotal is calculated (excluding items tagged "meta-exclude-gift")
-- Tiers are evaluated from highest to lowest
-- $250 tier doesn't qualify ($150 < $250)
-- $100 tier DOES qualify ($150 >= $100)
-- Product "6640591011912" (Goldie Mystery ZOX) gets 100% discount
-- Lower tiers ($75) are NOT applied
+- All qualifying tiers are found:
+  - $75 tier qualifies ($150 >= $75)
+  - $100 tier qualifies ($150 >= $100)
+  - $250 tier doesn't qualify ($150 < $250)
+- Products get 100% discount:
+  - "6638547533896" (Colorwheel F&F) - from $75 tier
+  - "6640591011912" (Goldie Mystery ZOX) - from $100 tier
+- Customer receives BOTH gifts (cumulative/stacking)
+
+---
+
+## Example 12: Multi-Tier Bundle Upgrade (Highest Only)
+
+**Use Case:** Offer tiered bundle upgrades where higher spend gets a better bundle product. Only the highest qualifying tier is applied (stackTiers: false).
+
+```json
+{
+  "__type": "MultiTierDiscount",
+  "label": "Spring Bundle Upgrade",
+  "active": true,
+  "description": "Spend more, get a better bundle!",
+  "inputs": [
+    ":all",
+    [],
+    [
+      {
+        "threshold": 75,
+        "discount": {
+          "__type": "PercentageDiscount",
+          "inputs": [100, "Free Starter Bundle"]
+        },
+        "productIds": ["1111111111111"],
+        "itemsToDiscount": 1,
+        "label": "Free Starter Bundle"
+      },
+      {
+        "threshold": 150,
+        "discount": {
+          "__type": "PercentageDiscount",
+          "inputs": [100, "Free Premium Bundle"]
+        },
+        "productIds": ["2222222222222"],
+        "itemsToDiscount": 1,
+        "label": "Free Premium Bundle"
+      },
+      {
+        "threshold": 300,
+        "discount": {
+          "__type": "PercentageDiscount",
+          "inputs": [100, "Free Deluxe Bundle"]
+        },
+        "productIds": ["3333333333333"],
+        "itemsToDiscount": 1,
+        "label": "Free Deluxe Bundle"
+      }
+    ],
+    ["meta-exclude-gift"],
+    false
+  ]
+}
+```
+
+**How It Works (stackTiers: false):**
+- Customer adds items to cart totaling $200
+- Cart subtotal is calculated (excluding items tagged "meta-exclude-gift")
+- Highest qualifying tier is selected:
+  - $75 tier qualifies ($200 >= $75)
+  - $150 tier qualifies ($200 >= $150) ✓ HIGHEST
+  - $300 tier doesn't qualify ($200 < $300)
+- Only the Premium Bundle gets 100% discount:
+  - "2222222222222" (Premium Bundle) - from $150 tier
+- Customer receives ONLY the Premium Bundle (not the Starter Bundle)
+
+---
 
 **Key Features:**
 - Automatically excludes gift items from threshold calculation
-- Only applies the highest qualifying tier (no stacking)
+- **stackTiers: true** - Applies ALL qualifying tiers (cumulative)
+- **stackTiers: false** - Applies ONLY the highest qualifying tier
 - Supports product IDs or product tags per tier
 - Perfect for seasonal promotions with start/end dates
 
@@ -436,6 +507,9 @@ export function run(input) {
    - `itemsToDiscount` - Maximum items to discount (optional, defaults to all)
    - `label` - Display name for the tier (optional)
 4. **Exclude Tags** - Array of product tags to exclude from subtotal calculation (default: `["meta-exclude-gift"]`)
+5. **Stack Tiers** - Boolean (default: `true`)
+   - `true` - Apply all qualifying tiers (cumulative GWP)
+   - `false` - Apply only highest tier (bundle upgrades)
 
 ---
 

package/dist/common/CampaignFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CampaignFactory.d.ts","sourceRoot":"","sources":["../../src/common/CampaignFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAEV,SAAS,EAIV,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAa,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAiC5C,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,CACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,WAAW,GACX,OAAO,EAAE,GACT,MAAM,EAAE,GACR,MAAM,EAAE,GACR,WAAW,EAAE,CAChB,EAAE,CAAC;CACL,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG;IAC9C,MAAM,EAAE,UAAU,GAAG,qBAAqB,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,qBAAa,eAAe;IAC1B,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,mBAAmB,GACI,QAAQ;IAG/D,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAuB/B,MAAM,CAAC,kBAAkB,CACvB,MAAM,EAAE,WAAW,GAEjB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,UAAU,GACV,QAAQ,GACR,iBAAiB,GACjB,SAAS;CAyHd"}
+{"version":3,"file":"CampaignFactory.d.ts","sourceRoot":"","sources":["../../src/common/CampaignFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAEV,SAAS,EAIV,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAa,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAiC5C,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,CACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,WAAW,GACX,OAAO,EAAE,GACT,MAAM,EAAE,GACR,MAAM,EAAE,GACR,WAAW,EAAE,CAChB,EAAE,CAAC;CACL,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG;IAC9C,MAAM,EAAE,UAAU,GAAG,qBAAqB,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,qBAAa,eAAe;IAC1B,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,mBAAmB,GACI,QAAQ;IAG/D,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAuB/B,MAAM,CAAC,kBAAkB,CACvB,MAAM,EAAE,WAAW,GAEjB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,UAAU,GACV,QAAQ,GACR,iBAAiB,GACjB,SAAS;CA0Hd"}

package/dist/common/CampaignFactory.js

@@ -55,7 +55,7 @@ class CampaignFactory {
             case 'ShippingDiscount':
                 return new ShippingDiscount_1.ShippingDiscount(args[0], args[1], args[2], args[3]);
             case 'MultiTierDiscount':
-                return new MultiTierDiscount_1.MultiTierDiscount(args[0], args[1], args[2], args[3]);
+                return new MultiTierDiscount_1.MultiTierDiscount(args[0], args[1], args[2], args[3], args[4]);
             case 'AndSelector':
                 return new AndSelector_1.AndSelector([...args]);
             case 'OrSelector':

package/dist/lineItem/MultiTierDiscount.d.ts

@@ -16,28 +16,32 @@ export interface Tier {
  * MultiTierDiscount - Applies tiered discounts based on cart subtotal
  *
  * This campaign evaluates the cart total (excluding gifts) and applies
- * the discount from the highest qualifying tier.
+ * discounts based on the stackTiers configuration:
  *
- * Example use case: Tiered gift with purchase
- * - Spend $75: Get free product A
- * - Spend $100: Get free product B
- * - Spend $250: Get free product C
+ * - stackTiers: true (default) - Applies ALL qualifying tiers (cumulative)
+ *   Example: Spend $150 → Get products from both $75 and $100 tiers
  *
- * Only the highest qualifying tier is applied (e.g., if cart is $150,
- * only the $100 tier applies, not both $75 and $100).
+ * - stackTiers: false - Applies ONLY the highest qualifying tier
+ *   Example: Spend $150 → Get product from $100 tier only
+ *
+ * Use cases:
+ * - Cumulative GWP: Spend more, get more gifts (stackTiers: true)
+ * - Bundle upgrades: Spend more, get better bundle (stackTiers: false)
  */
 export declare class MultiTierDiscount extends Campaign {
     tiers: Tier[];
     excludeGiftTags: string[];
-    constructor(behavior: QualifierBehavior, qualifiers: [Qualifier | AndSelector | OrSelector], tiers: Tier[], excludeGiftTags?: string[]);
+    stackTiers: boolean;
+    constructor(behavior: QualifierBehavior, qualifiers: [Qualifier | AndSelector | OrSelector], tiers: Tier[], excludeGiftTags?: string[], stackTiers?: boolean);
     /**
      * Calculate cart subtotal excluding gift items
      */
     private calculateCartSubtotal;
     /**
-     * Find the highest qualifying tier based on cart subtotal
+     * Find all qualifying tiers based on cart subtotal
+     * Returns tiers in descending order by threshold (highest first)
      */
-    private findQualifyingTier;
+    private findQualifyingTiers;
     /**
      * Filter line items that match the tier's product criteria
      */

package/dist/lineItem/MultiTierDiscount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MultiTierDiscount.d.ts","sourceRoot":"","sources":["../../src/lineItem/MultiTierDiscount.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAEV,iBAAiB,EAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EACV,iBAAiB,EACjB,SAAS,EACV,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,MAAM,WAAW,IAAI;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;IAC7C,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,eAAe,EAAE,MAAM,EAAE,CAAC;gBAGxB,QAAQ,EAAE,iBAAiB,EAC3B,UAAU,EAAE,CAAC,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC,EAClD,KAAK,EAAE,IAAI,EAAE,EACb,eAAe,GAAE,MAAM,EAA0B;IASnD;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA8B7B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA+B9B,GAAG,CAAC,YAAY,EAAE,YAAY,GAAG,YAAY;CA2E9C"}
+{"version":3,"file":"MultiTierDiscount.d.ts","sourceRoot":"","sources":["../../src/lineItem/MultiTierDiscount.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAEV,iBAAiB,EAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EACV,iBAAiB,EACjB,SAAS,EACV,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,MAAM,WAAW,IAAI;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;IAC7C,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;gBAGlB,QAAQ,EAAE,iBAAiB,EAC3B,UAAU,EAAE,CAAC,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC,EAClD,KAAK,EAAE,IAAI,EAAE,EACb,eAAe,GAAE,MAAM,EAA0B,EACjD,UAAU,GAAE,OAAc;IAU5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA8B7B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA+B9B,GAAG,CAAC,YAAY,EAAE,YAAY,GAAG,YAAY;CAqF9C"}

package/dist/lineItem/MultiTierDiscount.js

@@ -6,24 +6,28 @@ const Campaign_1 = require("../common/Campaign");
  * MultiTierDiscount - Applies tiered discounts based on cart subtotal
  *
  * This campaign evaluates the cart total (excluding gifts) and applies
- * the discount from the highest qualifying tier.
+ * discounts based on the stackTiers configuration:
  *
- * Example use case: Tiered gift with purchase
- * - Spend $75: Get free product A
- * - Spend $100: Get free product B
- * - Spend $250: Get free product C
+ * - stackTiers: true (default) - Applies ALL qualifying tiers (cumulative)
+ *   Example: Spend $150 → Get products from both $75 and $100 tiers
  *
- * Only the highest qualifying tier is applied (e.g., if cart is $150,
- * only the $100 tier applies, not both $75 and $100).
+ * - stackTiers: false - Applies ONLY the highest qualifying tier
+ *   Example: Spend $150 → Get product from $100 tier only
+ *
+ * Use cases:
+ * - Cumulative GWP: Spend more, get more gifts (stackTiers: true)
+ * - Bundle upgrades: Spend more, get better bundle (stackTiers: false)
  */
 class MultiTierDiscount extends Campaign_1.Campaign {
     tiers;
     excludeGiftTags;
-    constructor(behavior, qualifiers, tiers, excludeGiftTags = ['meta-exclude-gift']) {
+    stackTiers;
+    constructor(behavior, qualifiers, tiers, excludeGiftTags = ['meta-exclude-gift'], stackTiers = true) {
         super(behavior, qualifiers);
         // Sort tiers by threshold descending (highest first)
         this.tiers = [...tiers].sort((a, b) => b.threshold - a.threshold);
         this.excludeGiftTags = excludeGiftTags;
+        this.stackTiers = stackTiers;
     }
     /**
      * Calculate cart subtotal excluding gift items
@@ -49,15 +53,11 @@ class MultiTierDiscount extends Campaign_1.Campaign {
         return subtotal;
     }
     /**
-     * Find the highest qualifying tier based on cart subtotal
+     * Find all qualifying tiers based on cart subtotal
+     * Returns tiers in descending order by threshold (highest first)
      */
-    findQualifyingTier(cartSubtotal) {
-        for (const tier of this.tiers) {
-            if (cartSubtotal >= tier.threshold) {
-                return tier;
-            }
-        }
-        return null;
+    findQualifyingTiers(cartSubtotal) {
+        return this.tiers.filter(tier => cartSubtotal >= tier.threshold);
     }
     /**
      * Filter line items that match the tier's product criteria
@@ -89,61 +89,70 @@ class MultiTierDiscount extends Campaign_1.Campaign {
         }
         // Calculate cart subtotal (excluding gifts)
         const cartSubtotal = this.calculateCartSubtotal(discountCart);
-        // Find the highest qualifying tier
-        const qualifyingTier = this.findQualifyingTier(cartSubtotal);
-        if (!qualifyingTier) {
+        // Find qualifying tiers based on stackTiers configuration
+        const allQualifyingTiers = this.findQualifyingTiers(cartSubtotal);
+        if (allQualifyingTiers.length === 0) {
             // Cart doesn't meet minimum threshold
             return discountCart;
         }
-        // Get line items that match this tier's product criteria
-        const applicableLineItems = this.getApplicableLineItems(discountCart, qualifyingTier);
-        if (applicableLineItems.length === 0) {
-            // No matching products found
-            return discountCart;
-        }
-        // Sort by price (ascending) to discount cheapest items first
-        applicableLineItems.sort((a, b) => {
-            const priceA = parseFloat(String(a.cost.amountPerQuantity.amount));
-            const priceB = parseFloat(String(b.cost.amountPerQuantity.amount));
-            return priceA - priceB;
-        });
-        const itemsToApplyDiscounts = [];
-        let remainingDiscounts = qualifyingTier.itemsToDiscount;
-        // Apply discount to matching items up to the limit
-        applicableLineItems.forEach((lineItem) => {
-            if (remainingDiscounts === 0)
-                return;
-            if (remainingDiscounts !== undefined) {
-                // Apply to as many items as possible up to the limit
-                if (lineItem.quantity >= remainingDiscounts) {
-                    itemsToApplyDiscounts.push({
-                        lineItem,
-                        maxDiscounts: remainingDiscounts,
-                    });
-                    remainingDiscounts = 0;
+        // Select tiers to apply based on stackTiers configuration
+        // Note: allQualifyingTiers is sorted by threshold descending (from constructor)
+        // so allQualifyingTiers[0] is the highest qualifying tier
+        const tiersToApply = this.stackTiers
+            ? allQualifyingTiers // Apply all qualifying tiers (cumulative)
+            : [allQualifyingTiers[0]]; // Apply only highest tier
+        // Apply each selected tier
+        for (const tier of tiersToApply) {
+            // Get line items that match this tier's product criteria
+            const applicableLineItems = this.getApplicableLineItems(discountCart, tier);
+            if (applicableLineItems.length === 0) {
+                // No matching products found for this tier
+                continue;
+            }
+            // Sort by price (ascending) to discount cheapest items first
+            applicableLineItems.sort((a, b) => {
+                const priceA = parseFloat(String(a.cost.amountPerQuantity.amount));
+                const priceB = parseFloat(String(b.cost.amountPerQuantity.amount));
+                return priceA - priceB;
+            });
+            const itemsToApplyDiscounts = [];
+            let remainingDiscounts = tier.itemsToDiscount;
+            // Apply discount to matching items up to the limit
+            applicableLineItems.forEach((lineItem) => {
+                if (remainingDiscounts === 0)
+                    return;
+                if (remainingDiscounts !== undefined) {
+                    // Apply to as many items as possible up to the limit
+                    if (lineItem.quantity >= remainingDiscounts) {
+                        itemsToApplyDiscounts.push({
+                            lineItem,
+                            maxDiscounts: remainingDiscounts,
+                        });
+                        remainingDiscounts = 0;
+                    }
+                    else {
+                        // Apply to all items in this line
+                        itemsToApplyDiscounts.push({
+                            lineItem,
+                            maxDiscounts: lineItem.quantity,
+                        });
+                        remainingDiscounts -= lineItem.quantity;
+                    }
                 }
                 else {
-                    // Apply to all items in this line
+                    // No limit, apply to all matching items
                     itemsToApplyDiscounts.push({
                         lineItem,
                         maxDiscounts: lineItem.quantity,
                     });
-                    remainingDiscounts -= lineItem.quantity;
                 }
-            }
-            else {
-                // No limit, apply to all matching items
-                itemsToApplyDiscounts.push({
-                    lineItem,
-                    maxDiscounts: lineItem.quantity,
-                });
-            }
-        });
-        // Apply the tier's discount to all selected items
-        itemsToApplyDiscounts.forEach((item) => {
-            const discount = qualifyingTier.discount;
-            discount.apply([item]);
-        });
+            });
+            // Apply the tier's discount to all selected items
+            itemsToApplyDiscounts.forEach((item) => {
+                const discount = tier.discount;
+                discount.apply([item]);
+            });
+        }
         return discountCart;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoxllc/shopify-checkout-extensions",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Configuration-driven runtime engine for Shopify checkout extensions - campaigns, discounts, qualifiers, and selectors",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",