Cart evaluation

Cart evaluation is the checkout conversation with Loyal Guru. Your POS, e-commerce, app, or middleware sends the Customer and the lines they are buying. Loyal Guru answers which promotions apply, and — depending on the model — either calculates the new prices or only returns eligibility.

This page is the decision guide for the Loyalty and Promotional Engine. Endpoint schemas live in the OpenAPI Reference.

Use case

A grocer needs one answer at the till: which discounts and points apply to this Customer and this cart, before the receipt is printed. Another retailer already calculates price in the POS and only needs Loyal Guru to say which campaigns and Vouchers are valid.

Evaluation options

Option	When to use it	What Loyal Guru does	What your system does
Loyal Guru calculates	Checkout can call the API during the sale and wants Loyal Guru to own the price.	Evaluates the cart and returns discount effects and totals.	Simulate if you need a preview, then create the cart on payment.
You calculate	Checkout can call during the sale, but POS already owns pricing.	Returns eligibility, campaign data, and coupon or Voucher validation.	Calculate the price locally, then confirm usage.

Loyal Guru is always the source of truth for who is eligible and which rules apply. The only question is who performs the final price calculation.

Real-time evaluation

Use this when the checkout can send the cart before payment finishes.

1. Identify the Customer (card, app, phone, or anonymous).
2. Send POST /carts/simulate as lines change, if the UI needs a live preview.
3. When the Customer pays, send POST /carts/realtime with the same cart context.
4. Apply the response on the receipt: discounts, points, cashback, Voucher usage.

Flag	Meaning
apply_discounts: true	Loyal Guru calculates discount amounts.
apply_points: true	Loyal Guru calculates points or wallet earn.
cashback_score_desired	Balance the Customer wants to burn as cashback.

Simulate does not create the cart. Cart creation commits Voucher usage, points, and campaign limits. If payment fails after cart creation, use cart cancellation.

See New Engine Promo Engine and the product Promo Engine page.

You calculate the price

Use this when the POS or e-commerce engine already computes the cart value.

1. Ask Loyal Guru which campaigns, coupons, and Vouchers apply.
2. Calculate the price in your system.
3. Confirm usage so limits and Voucher state stay correct.

This is the New Engine Coupon Server model. Details: Coupon Server and Vouchers redeem vs Discounts redeem.

Reading campaign JSON without a cart is Reading from GET. Use it for display or a local engine — not as a substitute for cart creation when the sale actually happened.

What each model supports

The engine can evaluate discounts, points campaigns, cashback, coupons, Vouchers, stackability, and limits in one cart. The exact mechanic list depends on the Company engine and the integration model.

Need	Model
Loyal Guru prints the discounted totals	New Engine Promo Engine
POS prints the totals, Loyal Guru owns eligibility	New Engine Coupon Server
Existing legacy coupon integration	Legacy Coupon Server

Implementation notes

• Always send a cart, not a ticket or basket payload name.
• Identify the Customer when you have a card, app id, or phone. Anonymous carts still evaluate mass promotions.
• coupons_desired controls which coupon-gated or Voucher-gated campaigns enter the calculation. See Promo Engine.
• Retry cart creation with the same Idempotency-Key so a network retry does not double-apply.
• Company-level scope can be overridden per transaction. Confirm the default with the Loyal Guru team before go-live.

OpenAPI references

• Cart endpoints
• HTTP API and authentication
• Discount endpoints

Troubleshooting

Symptom	Check
Preview looks right, receipt is different	Cart creation used a different cart, Customer, store, or coupons_desired than simulate.
Discount missing in real time	Campaign dates, store, Audience, Voucher ownership, stackability, and limits.
POS price does not match Loyal Guru	You are on Coupon Server: your system owns the amount. Compare eligibility, not totals.
Effects applied twice	Cart creation retried without an idempotency key, or simulate was treated as cart creation.

Related product terms

Cart, coupon, Voucher, simulate, and cart creation use the Product Docs glossary terms when that page is published.