☰ 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/calculateScope: 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
truewhen 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_idis missing or bound to no location. When both point to different locations,register_idwins. 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_checkorper_day. - location, redeem_allowed, redeem_blocked_reason
- Only when
register_idis 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"withmax_redeem0.limited_byis thenlocation. The location is found byregister_idorstore_id; thelocationobject carriesstore_codeandmatched_by. - discount_typeobject or null
- Only when the venue uses discount types and the request sent one: the check's type with
earnandredeem. Withredeem: falsethe answer hasmax_redeem0,limited_by: "discount_type"andredeem_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_idwas sent. - stamps_earned, reward_unlocked, discount_percent
- For stamp and visit programs.
- displayobject
cashier_textandreceipt_linesin the guest's language.