What is the Promotion Calculator?
The Promotion Calculator is a dedicated page within the Promotion Engine that allows you to safely and quickly test which configured promotions apply to a specific cart setup. It enables you to verify your promotion rules without creating real orders or affecting live data. This tool helps you ensure your promotions work as expected in real business scenarios, provides immediate feedback on valid promotions for your test cart, and lets you experiment freely since tests do not impact usage limits or reporting.
How to use it?
1. Build your cart on the left side of the page
Cart Request
Enter a Cart Id or click Generate Cart ID to generate one.
The system recognizes that the requests originate from the Calculator tool to avoid conflicts with real carts provided in cart requests.
Add the Store Group and Store where you want to test promotions.
Select a rounding strategy, options include:
Mathematical: All decimal values will be rounded according to general mathematical rounding rules
Ceiling: All decimal values will be rounded up.
Floor: All decimal values will be rounded down.
Enter the precision value, the number of decimal places to use when rounding numbers (e.g., 2 means prices are rounded to 2 decimal places, like 12.34).
Select cart currency.
Promotions might behave differently depending on currency configuration, so choose the one matching your test scenario.
Price values of items within the cart will be considered in this currency.Select the cart timezone.
Time-based promotions depend on timezone settings for accurate activation and expiry times, so choose the timezone relevant to your test case.
Cart items
Click Add Cart Item + to start adding an item to the cart.
You must add at least one product to the cart.Enter the cart item product category for the item you are adding.
This helps the system identify the product’s classification, which can affect promotion eligibility.Enter the specific product.
This uniquely identifies the product you want to test within the cart.Specify how many units (quantity) of the product you want in the cart.
This number affects promotions that depend on quantity thresholds.Enter the price for a single unit of the product before tax.
The currency will always match the cart currency you selected earlier.Enter the tax amount applied to a single unit of the product.
This also uses the cart currency.
You can use the Add Cart Item + to add further items to the cart.
Promo Code
If your promotion requires a promo code, enable this option and enter the code here. This lets you test promotions that only activate when a specific code is used.
2. Run the test
Once your cart details are complete, click the Calculate button to see which promotions apply.
The Promotion Engine will recognize this as a test, so it will:
Not save the request data in the database
Exclude this request from usage counts and reports
How does the calculation work?
The logic behind the Promotion Calculator mirrors how the Promotion Engine calculates applicable promotions via /cart or /checkout endpoints.
When a request is received, the engine evaluates all configured promotions to determine which ones are active, valid, and eligible for the given cart based on configured settings. It checks whether the cart meets the required conditions (such as product combinations, quantities, or promo codes) and whether the promotions can be applied together.
If multiple valid promotions are found, the engine selects the optimal combination (for example, the one that gives the best total discount). Promotions that conflict with more beneficial ones, or that would result in an invalid outcome (e.g., making the final cart value negative) are excluded.
3. View results
On the right side of the page, the Show Discounts view displays the list of promotions applicable to your test cart, along with details on how they would apply.
You can switch to the Show Response view to see the full JSON response that would be returned by the /cart Promotion Engine API endpoint for a request with the provided details. Use the toggle button to switch back and forth between Show Discounts and Show Response views anytime.
This allows you to easily review both a user-friendly summary of applicable promotions and the exact API response for deeper inspection.
Show Discounts view
Show response view
Tips for effective testing with the Calculator
Use realistic cart data that closely resembles what your customers purchase to get accurate results.
Test different promo codes, product combinations, quantities, and prices to cover as many scenarios as possible.
After updating or creating new promotion rules, run tests regularly to catch configuration errors early.
Try testing recurring promotions with different dates and times to verify timing settings work as expected.
If a promotion is not applying as expected, double-check store and store group settings, currency, and timezone selections in your test cart.
Remember, tests do not affect your live promotion limits or analytics.