Custom Promotion Scripts

This basic script automatically adds a discount to _all_ items in all baskets of the cart.

class UniversalBasicItemDiscount extends PromotionScript {
    process() {
        for (const basket of this.cart.baskets) {
            for (const item of basket.items) {
                item.applyDiscount(this.discount);
            }
        }
    }
}

This script automatically adds a discount to all items in a given category. The category is specified by its ref num (aka External ID) in a eligible_category_ref_num custom parameter for this promotion script.

class CategoryItemDiscount extends PromotionScript {
    process() {
        for (const basket of this.cart.baskets) {
            for (const item of basket.items) {
                if (item.product.categories_ref_nums.includes(this.parameters.eligible_category_ref_num)) {
                    item.applyDiscount(this.discount);
                }
            }
        }
    }
}

This script handles a variety of “Buy x, get y with some discount” promotions to be applied to any products within a given category.

Script Parameters:

[
    {"name":"eligible_category_ref_num","type":"text"},
    {"name":"buy_x","type":"integer"},
    {"name":"get_y","type":"integer"},
    {"name":"exclusive","type":"integer"},
    {"name":"maximum_number_of_discounted_items","type":"integer"}
]

Example values

{"eligible_category_ref_num":"category-mens-t-shirts","buy_x":1,"get_y":1,"exclusive":0,"maximum_number_of_discounted_items":-1}

Where:

• eligible_category_ref_num determines base eligibility (i.e. items whose products are in the category specified by eligible_category_ref_num can participate in the discount)
• buy_x determines how many non-discounted items must be present in the basket to open up a set of discounts
• get_y determines how many discounts will be able to be applied for each set of discounts
• maximum_number_of_discounted_items determines the maximum number of items this discount can be applied to
• exclusive is a flag to control whether already-discounted items are eligible to have the “get y” discount stacked on their existing discounts.

It applies the logic that the items receiving the discount (i.e. the “get y” ) must be equal or lesser in price to the corresponding “buy x” items (which must also be non-discounted).

e.g. Suppose you have a 20% off promotion using this script with parameters buy_x: 3, get_y: 2, maximum_number_of_discounted_items: 3, and a cart containing 10 eligible items with no prior discounts and the following prices:

1. $110
2. $109
3. $108
4. $107
5. $106
6. $105
7. $104
8. $103
9. $102
10. $101

What would happen is:

• Items 1, 2, and 3 would collectively trigger the first “buy 3” set
• Items 4 and 5 would each receive a 20% discount as members of the first “get 2” set
• Items 6, 7, and 8 would trigger the second “buy 3” set
• Item 9 would receive a 20% discount as a member of the second “get 2” set
• Item 10 would not receive a discount because maximum_number_of_discounted_items: 3, and items 4, 5, and 9 have already used up that maximum.

A classic “Buy 1 Get 1 Free” promotion can be configured using this script by creating a promotion with a 100% discount and buy_x: 1, get_y: 1 as parameter values.

class BuyXGetYInCategory extends PromotionScript {
    process() {
        for (const basket of this.cart.baskets) {
            let eligible_items = [];

            for (const item of basket.items) {
                if (item.product.categories_ref_nums.includes(this.parameters.eligible_category_ref_num)) {
                    if (this.parameters.exclusive != 0 && item.hasOrRelatesToDiscounts()) {
                        console.debug("Skipping item " + item.product.ref_num + " because it already has " + item.applied_discounts.length + " discounts");
                        continue;
                    }
                    eligible_items.push(item);
                }
            }

            // Sort by descending price
            eligible_items.sort((a, b) => b.price - a.price);

            let unused_donors = [];
            let currently_using_donors = [];

            let unused_donor_count = 0;
            let unused_recipient_count = 0;

            let most_recent_donor_price = 0;

            let number_of_discounted_items = 0;
            let maximum_number_of_discounted_items = this.parameters.maximum_number_of_discounted_items;

            if (maximum_number_of_discounted_items < 0) {
                maximum_number_of_discounted_items = Infinity;
            }

            let eligible_recipients_past = [];

            // Items are divided into 'donors' (which sit on the 'buy x' side),
            // and 'recipients' (which receive the 'get y' discount).

            // Within each matched subset of donors and recipients:
            // 1. the donors must all be non-discounted
            // 2. the price of each donor must be greater than
            //    the prices of any recipient.
            // 3. recipients may optionally already have discounts if
            //    allowed by 'exclusive' flag.
            //
            // We seek to ensure that the highest discount is granted,
            // subject to the above.
            //
            // i.e. if there are eligible items worth [$100, $90, $50, $40],
            // and buy_x=1, get_y=1, then:
            // - the $100 item should enable the discount to be applied to
            //   the $90 item
            // - then the $50 item should enable discounting the $40 item
            //
            // However, suppose exclusive=false, and the $100 item has
            // another discount. In this case, it cannot be a donor,
            // but it can still be a recipient.
            //
            // TODO: look at post-discounted amount instead of price?
            //

            for (const item of eligible_items) {
                if (unused_donor_count >= this.parameters.buy_x) {
                    unused_donor_count -= this.parameters.buy_x;
                    currently_using_donors = unused_donors;
                    unused_donors = [];
                    unused_recipient_count += this.parameters.get_y;
                }

                while (unused_recipient_count > 0 && eligible_recipients_past.length > 0 && number_of_discounted_items < maximum_number_of_discounted_items) {
                    recipient = eligible_recipients_past.shift();
                    if (recipient.price <= most_recent_donor_price) {
                        console.debug("Applying discount to previously skipped item " + recipient.product.ref_num);
                        recipient.applyDiscount(this.discount);
                        number_of_discounted_items += 1;
                        unused_recipient_count -= 1;

                        // Mark the donor items as being used
                        for (const donor_item of currently_using_donors) {
                            donor_item.markAsRelatedToDiscount(this.discount);
                        }
                        currently_using_donors = [];
                    }
                }

                if (unused_recipient_count > 0 && number_of_discounted_items < maximum_number_of_discounted_items) {
                    item.applyDiscount(this.discount);
                    number_of_discounted_items += 1;
                    unused_recipient_count -= 1;

                    // Mark the donor items as being used
                    for (const donor_item of currently_using_donors) {
                        donor_item.markAsRelatedToDiscount(this.discount);
                    }
                    currently_using_donors = [];
                } else {
                    if (this.parameters.exclusive == 0 && item.hasOrRelatesToDiscounts()) {
                        // Item cannot be a donor, but it can be a recipient
                        console.debug("Item " + item.product.ref_num + " cannot be donor but can be recipient, adding to eligible past array");
                        eligible_recipients_past.push(item);
                    } else {
                        unused_donor_count += 1;
                        unused_donors.push(item);

                        most_recent_donor_price = item.price;
                    }
                }
            }

            // If the last item was a donor, need to check if it can apply to earlier items
            if (unused_donor_count >= this.parameters.buy_x) {
                unused_donor_count -= this.parameters.buy_x;
                currently_using_donors = unused_donors;
                unused_donors = [];
                unused_recipient_count += this.parameters.get_y;
            }

            while (unused_recipient_count > 0 && eligible_recipients_past.length > 0 && number_of_discounted_items < maximum_number_of_discounted_items) {
                recipient = eligible_recipients_past.shift();
                if (recipient.price <= most_recent_donor_price) {
                    console.debug("Applying discount to previously skipped item " + recipient.product.ref_num);
                    recipient.applyDiscount(this.discount);
                    number_of_discounted_items += 1;
                    unused_recipient_count -= 1;

                    // Mark the donor items as being used
                    for (const donor_item of currently_using_donors) {
                        donor_item.markAsRelatedToDiscount(this.discount);
                    }
                    currently_using_donors = [];
                }
            }
        }
    }
}