☰ Menu · Calculate
API reference

Calculate a check

Ask what a check would earn and redeem before the guest pays. Nothing is written.

POST/v1/checks/calculate
Scope: transactions:write or devices:write

Applies the same rules as POST /v1/transactions: the guest's level, category rules, the program's share, the venue's limits and holds. Call it as often as the basket changes. Another register could still spend the balance before the check closes; use a hold when that matters.

memberstring, required
Card number, scanned value, serial, member id or phone.
amountinteger, required
The check total before cashback, minor units.
redeem_amountinteger
How much the guest wants to pay with cashback.
hold_iduuid
Calculate as if this hold were captured.
discount_typestring
The discount code of the check, as on a transaction. Lines can carry their own.
line_items[].promoboolean
true when the item is on promotion. The owner's promo rules then decide whether the line earns and whether it can be paid with cashback. Ignored where the venue has not turned the rule on.
register_idstring
Your register code. When the owner bound it to a location, the location's rules apply to the calculation.
store_idstring
The store (location) code from your accounting system, up to 64 characters. Used when register_id is missing or bound to no location. When both point to different locations, register_id wins. See how to send the location and the register.
cashierstring or object
Accepted as on a transaction, so the till can send one body. A calculation stores nothing.
line_itemsarray
Same as on a transaction; used by category rules.
curl
curl https://loyaltyfy.io/api/v1/checks/calculate \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "member": "2000111703779", "amount": 20000, "redeem_amount": 5000 }'
Response · 200
{
  "object": "check_calculation",
  "amount": 20000,
  "redeem_amount": 1250,
  "max_redeem": 1250,
  "limited_by": "balance",
  "net_amount": 18750,
  "cashback_earned": 938,
  "earn_rate": 5,
  "level": "Base",
  "balance_after": 938,
  "category_rules_applied": false,
  "line_items": [
    { "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee", "amount": 8000, "earn_percent": 5, "cashback_earned": 375, "redeemable": true },
    { "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 12000, "category": "Desserts", "amount": 12000, "earn_percent": 5, "cashback_earned": 563, "redeemable": true }
  ],
  "hold_required": false,
  "stamps_earned": 0,
  "reward_unlocked": false,
  "member": { "object": "member", ... },
  "display": {
    "cashier_text": "Paid with cashback: 12.50 MDL · Cashback earned: 9.38 MDL · Cashback balance: 9.38 MDL",
    "receipt_lines": [
      "Paid with cashback: 12.50 MDL",
      "Cashback earned: 9.38 MDL",
      "Cashback balance: 9.38 MDL"
    ]
  }
}
redeem_amountinteger
What would actually be redeemed.
max_redeeminteger
The most this check can redeem now.
limited_bystring or null
When the request asked for more: balance, program, per_check or per_day.
location, redeem_allowed, redeem_blocked_reason
Only when register_id is bound to a location with its own rules: the location, whether cashback can be redeemed there and, if not, redeem_blocked_reason: "redeem_not_allowed_here" with max_redeem 0. limited_by is then location. The location is found by register_id or store_id; the location object carries store_code and matched_by.
discount_typeobject or null
Only when the venue uses discount types and the request sent one: the check's type with earn and redeem. With redeem: false the answer has max_redeem 0, limited_by: "discount_type" and redeem_blocked_reason: "discount_redeem_not_allowed".
cashback_earned, earn_rate, level
What the check would earn and at which level.
balance_afterinteger
The balance after this check.
line_itemsarray
What each line would earn: amount, cashback_earned, earn_percent, redeemable. Show it on the receipt or next to the basket.
line_items[].promoboolean
Only for venues with promo rules: whether the line was sent as an item on promotion.
hold_requiredboolean
The venue redeems only through holds and no hold_id was sent.
stamps_earned, reward_unlocked, discount_percent
For stamp and visit programs.
displayobject
cashier_text and receipt_lines in the guest's language.