Simulate and Apply Points

Points simulation lets a retailer use Loyal Guru as a real-time loyalty calculator. Before the customer confirms payment, the checkout can show how much balance the customer will earn, whether cashback can be used, and how points campaigns interact with the current cart.

This is useful for customer-facing previews ("you will earn 120 pts"), staff-assisted checkout, e-commerce order summaries, and QA testing before launching a new points campaign.

What you can simulate

Simulation use case	What the response tells you
Points accrual	Which points campaigns apply and how much balance the customer earns
Wallet accrual	Monetary wallet amount awarded when the company uses money wallet mode
Cashback redemption	How much requested cashback can be applied to the cart
Tier multipliers	Whether the customer's tier changes the points result
Campaign limits	Whether per-customer frequency or transaction caps affect the award
Stackability	Which points campaigns stack or compete within their categories

Endpoint summary

Endpoint	Purpose	Persisted?
`POST /carts/simulate`	Preview points, wallet accrual, and cashback before payment confirmation	No
`POST /carts/realtime`	Confirm the cart and commit earned/spent balance	Yes

Simulation returns the calculation without posting balance to the customer ledger. Real-time cart creation persists the cart and commits the resulting points, wallet, and cashback movements.

Control points application

Use apply_points to decide whether the cart evaluates points campaigns:

Value	Behavior
`true`	Loyal Guru evaluates active points campaigns and returns `scores[]`.
`false`	The cart does not award points or wallet balance.
omitted	The company-level default configuration is used.

Use cashback_score_desired when the customer wants to redeem available balance as a cart discount. The response can include cashback_score_desired_unused if the requested amount cannot be fully applied.

Control coupon and voucher application

Points campaigns for loyalty members that do not require a coupon are included by default when apply_points: true. Use coupons_desired when the cart should also evaluate coupon-gated or voucher-gated campaigns.

`coupons_desired` value	Points behavior
`"all"`	Evaluate loyalty-member points campaigns without coupon, plus every voucher assigned to the customer.
`"selected"`	Evaluate loyalty-member points campaigns without coupon, plus only vouchers previously selected by the customer through the voucher selection flow.
`["POINTSBOOST", "34433"]`	Evaluate loyalty-member points campaigns without coupon, plus the listed static coupon codes or unique voucher codes.
`[]` or omitted	Evaluate only loyalty-member points campaigns without coupon. No specific voucher or coupon is requested.

The old vouchers_desired naming is deprecated; use coupons_desired. If a coupon has auto redeem enabled, the customer does not need to manually type a code in the checkout experience, but the cart request still controls whether all, selected, explicit, or no customer vouchers are evaluated.

Simulate points and cashback

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": 20260702003,
  "customer_id": 1042,
  "currency": "EUR",
  "country": "ES",
  "location_id": 12,
  "apply_discounts": false,
  "apply_points": true,
  "cashback_score_desired": 500,
  "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-OIL-1L",
      "product_code": "OIL1L",
      "quantity": 1,
      "unit_price": 9.90,
      "total": 9.90,
      "categories": ["pantry"]
    }
  ]
}

To simulate all assigned vouchers together with points and cashback:

{
  "id": 20260702003,
  "customer_id": 1042,
  "apply_points": true,
  "cashback_score_desired": 500,
  "coupons_desired": "all",
  "total": 68.50,
  "lines": [...]
}

Example response:

{
  "id": 20260702003,
  "apply_points": true,
  "cashback_score_desired": 500,
  "cashback_score_desired_unused": 0,
  "scores": [
    {
      "rule_id": 881,
      "rule_name": "Base earn rate",
      "score": 68,
      "score_available": 68
    },
    {
      "rule_id": 912,
      "rule_name": "Beverages multiplier",
      "score": 26,
      "score_available": 26
    }
  ],
  "effects": [
    {
      "type": "cashback",
      "value": -5.00
    }
  ]
}

Apply points to a confirmed cart

When the customer pays, submit the same cart to POST /carts/realtime.

POST /carts/realtime
X-Api-Key: your_api_key
X-Api-Secret: your_api_key_secret
X-Api-Version: 1
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001
Content-Type: application/json

After a successful real-time cart creation:

Points or wallet accrual is posted to the customer's ledger.
Activation and expiration rules are applied.
Cashback is redeemed if requested and available.
The cart can later be cancelled or partially returned, reversing the relevant balance movements.

How to read `scores[]`

Field	Meaning
`rule_id`	Points campaign that awarded balance
`rule_name`	Campaign name
`score`	Balance awarded by the campaign
`score_available`	Balance immediately available after activation rules

If scores[] is empty, no points campaign qualified for that cart. Check customer identity, audience, event type, currency, country, conditions, limits, and apply_points.

What you can simulate​

Endpoint summary​

Control points application​

Control coupon and voucher application​

Simulate points and cashback​

Apply points to a confirmed cart​

How to read scores[]​

Related pages​