Promotions Engine: Version 1 vs 2 vs 3 vs 4

This page describes the different promotion check versions (v1–v4) and when to use each. The version is controlled by the check_promotions setting which can be set under Products → Settings → Options. All versions support the same promotion types (Price, Amount Off, Percent Off, Frequent Buyer), except for version 4 which added quantity (BOGO) support.

How the version is chosen

An admin can select the promotion version under Products → Settings → Options. This will set all locations to use that promotion version. There are currently 4 versions that can be selected. Below is a breakdown of what’s included in each version.

Version 1 (Original)

Best for: Legacy version supporting basic promotion features. This version is very consistent in how it calculates promotions, but does not support all features.

Does not support:

Max transactions per customer.
Invoice Split Lines.
BOGO (Buy N Get M): Basic quantity-style promotions only; full BOGO (e.g. buy 3 get 1 free on specific products) is not fully supported.
Performance: Can be slower on large baskets because everything is done in one big query.
Use when: You need the original behavior and don’t need v2/v3/v4 improvements.

Version 2 (Performance and split-line support)

Best for: Better performance and correct handling of transaction line grouping.

Does not support: Max transactions per customer.

Max transactions per customer.
BOGO: Same as v1; full BOGO is not fully supported.
Use when: You want the v1 behavior with better performance and correct line grouping, but don’t need “max transactions per customer” or full BOGO.

Version 3 (Max transactions per customer)

Best for: Promotions that are limited by how many transactions a customer can use them in.

The system counts how many distinct transactions the customer has already used the promotion in. If the promotion has a max (e.g. 2), the customer can only use it in that many transactions; after that, the promotion is no longer eligible for that customer even if other limits (e.g. per sale) are not reached.

Limits supported: Max uses, max per customer, max per sale, and max transactions per customer.
BOGO: Same as v2; full BOGO is not fully supported.
Use when: You need “use this promotion in at most N transactions per customer” (e.g. “max 2 transactions per customer”).

Version 4 (BOGO and modular engine)

Best for: Full support of all options, including Full BOGO (Buy N Get M) support.

BOGO: Full BOGO support. The engine explicitly handles:
Use when: This is the default version of promotions that should be used as it supports all options. The only reason you should consider running a prior version of promotions is if you find an issue.

Which version should I use?

Stay on v1 only if you need to preserve the original behavior and don’t need the fixes or new limits. This version is considered a legacy version and no new bug fixes or enhancements will be done to this version.
Use v2 if you want better performance and correct line handling, without “max transactions per customer” or BOGO. This version is considered a legacy version and no new bug fixes or enhancements will be done to this version.
Use v3 if you need “max transactions per customer” but not BOGO.
Use v4 if you run BOGO promotions or want the full set of limits.