Promo Engine
The Promo Engine is Loyal Guru's real-time decision layer for checkout. It lets retailers test, calculate, and apply promotions in milliseconds, combining discounts, points accrual, cashback redemption, coupons, and vouchers in a single cart evaluation.
For commercial teams, this works like a promotion calculator: before the customer pays, the checkout can ask Loyal Guru what would happen if this cart were confirmed right now. The response shows which campaigns apply, which discounts change the price, how many points or wallet balance the customer earns, and how much cashback can be redeemed.
What the engine can calculate
| Capability | What Loyal Guru evaluates |
|---|---|
| Discounts | Automatic discounts, club prices, coupon/voucher discounts, bundles, combo prices, stackability, limits |
| Points accrual | Points or wallet balance earned from active points campaigns |
| Cashback burn | Customer balance requested as a cart discount through cashback_score_desired |
| Coupons and vouchers | Code validation, voucher ownership, coupon eligibility, auto-redeem behavior |
| Campaign controls | Category priority, stackability, budgets, frequency limits, per-transaction caps |
The engine is designed for high-traffic retail checkout. Loyal Guru's public platform positioning describes sub-100ms promotional decisioning and real-time calculation for complex promotion and loyalty logic. Actual response time depends on cart size, active campaign volume, integration network latency, and company configuration.
Two cart modes
| Mode | Endpoint | What it is for | Persisted? |
|---|---|---|---|
| Simulate | POST /carts/simulate | Preview the result before the customer confirms payment | No |
| Create / apply | POST /carts/realtime | Confirm the cart, persist the transaction, and commit effects | Yes |
Use simulate when the experience needs a calculator: "You will save €8.50 and earn 120 pts if you continue." Use create / apply when the purchase is confirmed and the POS or e-commerce checkout needs the final result to print the receipt, update the customer's balance, and mark vouchers or cashback as used.
LG as promo engine
When Loyal Guru applies promotions in real time, the cart request enables the calculation flags:
| Flag | Meaning |
|---|---|
apply_discounts: true | Loyal Guru evaluates discounts and returns the adjusted cart values and effects[]. |
apply_points: true | Loyal Guru evaluates points campaigns and returns points or wallet accrual in scores[]. |
cashback_score_desired | Amount of customer balance requested as cashback for this cart. |
The POS or e-commerce system sends the cart once. Loyal Guru evaluates the complete promotional context and returns a single answer.
Control coupon and voucher application
Mass promotions and loyalty-member promotions that do not require a coupon are evaluated by default. Use coupons_desired to control which coupon-gated or voucher-gated campaigns are included in the cart calculation.
coupons_desired value | What Loyal Guru evaluates |
|---|---|
"all" | Mass and loyalty-member promotions without coupon, plus every voucher assigned to the customer. |
"selected" | Mass and loyalty-member promotions without coupon, plus only vouchers previously selected by the customer through the voucher selection flow. |
["SUMMER25", "34433"] | Mass and loyalty-member promotions without coupon, plus the listed static coupon codes or unique voucher codes. |
[] or omitted | Only mass and loyalty-member promotions without coupon. No specific coupon or voucher is requested. |
coupons_desired replaces the deprecated vouchers_desired naming. Coupon configuration still matters: when a coupon has auto redeem enabled, the customer does not need to manually type a code in the checkout experience, but the integration still controls whether all, selected, or explicit customer vouchers are included in the cart evaluation.
Example: one cart, all effects
This example combines:
- A loyalty member discount on beverages.
- A coupon code for a targeted promotion.
- Points accrual on the final qualifying cart.
- Cashback redemption requested by the customer.
POST /carts/simulate
X-Api-Key: your_api_key
X-Api-Secret: your_api_key_secret
X-Api-Version: 1
Content-Type: application/json
{
"id": 20260702001,
"customer_id": 1042,
"currency": "EUR",
"country": "ES",
"location_id": 12,
"apply_discounts": true,
"apply_points": true,
"cashback_score_desired": 500,
"coupons_desired": ["SUMMER25"],
"total": 68.50,
"lines": [
{
"product_id": "SKU-COFFEE-250",
"product_code": "COFFEE250",
"quantity": 2,
"unit_price": 6.50,
"total": 13.00,
"categories": ["beverages"]
},
{
"product_id": "SKU-CEREAL-500",
"product_code": "CEREAL500",
"quantity": 1,
"unit_price": 4.80,
"total": 4.80,
"categories": ["breakfast"]
},
{
"product_id": "SKU-OIL-1L",
"product_code": "OIL1L",
"quantity": 1,
"unit_price": 9.90,
"total": 9.90,
"categories": ["pantry"]
}
]
}
Example response structure:
{
"id": 20260702001,
"currency": "EUR",
"apply_discounts": true,
"apply_points": true,
"total": 60.00,
"cashback_score_desired": 500,
"cashback_score_desired_unused": 0,
"effects": [
{
"rule_id": 3210,
"rule_name": "Club beverage discount",
"type": "discount",
"effectType": "percentage",
"value": -1.30,
"line": 1
},
{
"rule_id": 3399,
"rule_name": "SUMMER25 coupon",
"type": "discount",
"effectType": "direct_value",
"value": -5.00,
"coupon_info": {
"coupon_name": "SUMMER25",
"voucher_code": "SUMMER25"
}
},
{
"type": "cashback",
"value": -5.00
}
],
"scores": [
{
"rule_id": 881,
"rule_name": "Base earn rate",
"score": 120,
"score_available": 120
}
]
}
Simulate vs apply
| Behavior | POST /carts/simulate | POST /carts/realtime |
|---|---|---|
| Returns applicable discounts | Yes | Yes |
| Returns points or wallet accrual | Yes | Yes |
| Shows requested cashback impact | Yes | Yes |
| Persists the cart | No | Yes |
| Commits points to the customer's balance | No | Yes |
| Consumes cashback or vouchers | No | Yes |
| Use case | Preview, calculator, pre-payment confirmation | Final checkout, receipt, loyalty ledger |