☰ Menu · Venue rules and limits
Venue rules and limits
How a venue controls what connected registers may do: cashback levels, product categories, holds, check numbering, late checks, limits and scan checks.
Everything on this page is set by the venue owner in Developers → Register rules. The rules apply to every API key of the venue; a single key (one register, one kiosk) can have its own values for any of them. Your integration reads the rules it works under from GET /v1/account, in settings.
"settings": {
"redemption": "hold",
"hold_minutes": 30,
"check_numbering": "per_register",
"offline_max_hours": 72,
"redeem_max_per_check": 50000,
"redeem_max_per_day": null,
"require_scan": true,
"scan_window_minutes": 30,
"allow_adjustments": false,
"adjustment_max": 50000,
"card_prefix": "2999"
}Cashback levels
A cashback program can have levels: for example Base 5%, Silver 7% from the second visit, Gold 10% from 1000.00 spent. Levels are counted by visits, by total spent, or by whichever comes first. The owner sets them in the loyalty program. Nothing is needed on the register side: every check earns at the guest's level after that check, and every member object tells you where the guest is.
"cashback": {
"balance": 10200,
"held": 0,
"available": 10200,
"currency": "MDL",
"earn_rate": 7,
"level": "Silver",
"level_basis": "any",
"levels": [
{ "name": "Base", "earn_rate": 5, "min_visits": null, "min_spent": null },
{ "name": "Silver", "earn_rate": 7, "min_visits": 2, "min_spent": null },
{ "name": "Gold", "earn_rate": 10, "min_visits": null, "min_spent": 100000 }
],
"next_level": { "name": "Gold", "earn_rate": 10, "visits_left": null, "spent_left": 80000 },
...
}next_level.visits_left and next_level.spent_left are ready to show the guest ("2 more visits to Silver"). display.receipt_lines already has that line in the guest's language.
Product categories
Upload your products with their category once, then send changes. Categories appear in the owner's dashboard, where each one can be set to: not earn cashback (tobacco, alcohol), not be payable with cashback (items already on promotion), or earn its own percent instead of the guest's level (coffee 10%). The API can create products and categories and rename them, but only the owner changes these rules.
curl https://loyaltyfy.io/api/v1/catalog/products/bulk \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"products": [
{ "sku": "4840001", "name": "Marlboro Gold", "category": "TOB", "category_name": "Tobacco", "price": 6500 },
{ "sku": "1001", "name": "Latte", "category": "COF", "category_name": "Coffee", "price": 4500 },
{ "sku": "2040", "name": "Zeama", "category": "KIT", "category_name": "Kitchen", "price": 6500 }
]
}'
# { "object": "catalog_sync", "upserted": 3 }Then send line_items with each check. A line can carry category, or only sku: we look the category up in the catalogue. Line totals are scaled to the check amount, so discounts made on the register side are spread fairly. Lines in categories without rules earn at the guest's level. Every transaction and POST /v1/checks/calculate return line_items with what each line earned, and a refund can name the returned lines. The owner can also override a category's rule on a single product, for good or only between two dates (a promotion).
curl https://loyaltyfy.io/api/v1/transactions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"external_id": "CHK-2026-000130",
"member": "2000111703779",
"amount": 17500,
"line_items": [
{ "sku": "4840001", "quantity": 1, "unit_price": 6500 },
{ "sku": "1001", "quantity": 1, "unit_price": 4500 },
{ "sku": "2040", "quantity": 1, "unit_price": 6500 }
]
}'
# Tobacco earns nothing, Coffee has its own 10%, Kitchen earns at the guest's level (5%):
# 0 + 450 + 325 = "cashback_earned": 775Venues with the detailed rule order switched on also accept in category the category name as the owner sees it in the catalogue ("Beer" as well as "106", in any case): the line then follows the rules of that category. A category name never creates a new category. A value the catalogue does not know falls back to the product's category by sku; only when the product has none does the value appear as a new category. The most specific rule wins: the product, then its category, then the program or level; a product with its own percent earns it even in a category that earns nothing. On a check below the program's minimum, or where the location does not earn, every line answers earn_percent: null and cashback_earned: 0, and below the minimum the check answers earn_rate: 0.
Paying with cashback through a hold
With In the check (the default) the register sends redeem_amount with the closed check. With Through a hold the register sets the amount aside when the guest asks to pay with cashback, and the closed check confirms it. If the check never arrives (the network dropped, the sale was cancelled), the hold is released after the time the owner set, and the guest keeps the money. No discount is ever given without being taken from the balance.
- 1Hold
POST /v1/holdswith the member, the amount and the check total. The same caps as for a check apply. The response has the holdid. - 2Capture
POST /v1/transactionswithhold_id. Leave outredeem_amountto use the whole hold, or send a smaller one. - 3Or release
POST /v1/holds/{id}/releasewhen the sale is cancelled. Releasing twice is harmless.
curl https://loyaltyfy.io/api/v1/holds \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hold-R3-000131" \
-d '{ "member": "2000111703779", "amount": 3000, "check_amount": 20000, "register_id": "R3" }'
# at payment: the check captures it
curl https://loyaltyfy.io/api/v1/transactions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "external_id": "000131", "register_id": "R3", "member": "2000111703779",
"amount": 20000, "hold_id": "5b0d6c1e-8f3a-4d7e-9a61-2c4b8e0f7d19" }'cashback.available of the member, in the limits, and in the venue's own cashier app, so the same money can't be spent twice.Check numbers per register
If each register counts checks from 1, choose Each register counts its own. Then register_id is required and we store the check as <register_id>:<external_id>, for example R3:15. Use that combined id to read, void or refund the check.
Card number prefix
Cards we issue get a 13-digit number. If the till recognises loyalty cards by the first digits, set a prefix in Developers → Register rules: new cards start with it. Digits stay within the 13 characters (prefix 2999 gives 2999 and 9 more digits), letters are put in front of them. Cards already issued keep their numbers, and a card_number sent with POST /v1/members always wins. The prefix is returned in settings.card_prefix of GET /v1/account.
Checks sent late
After an outage the register sends its queue. With a limit of, say, 72 hours, checks whose closed_at is older are refused with check_too_old, so a register restored from an old backup can't flood the venue with stale checks. A closed_at more than 10 minutes in the future is always refused.
Redeem limits
On top of the program's share of a check, the owner can set the most cashback per check and per guest per day (all registers together, by the venue's time zone). A check asking for more redeems what is allowed and the response shows the real redeem_amount; a hold asking for more is refused with limited_by. Use calculate to show the guest the exact number first.
Rules per location
The owner can bind register codes to a location in Locations. The code is the register_id your register sends with checks, calculations and holds. A location can switch earning off, set its own percent, forbid paying with cashback or set its own share of a check that may be paid with cashback. The owner also picks what wins when a product (category), the location and the guest's level all have a percent: product, location, level; location, product, level; or the guest's level over the location (the location percent then replaces only the base level). A category that earns nothing stays excluded in every order. Where paying with cashback is not allowed, POST /v1/checks/calculate answers max_redeem: 0 with redeem_blocked_reason, and a check or hold with cashback is refused with 400 redeem_not_allowed_here. A check without register_id, or with a code bound to no location, follows the general rules; unknown codes are listed for the owner to bind.
Order of rules
When the venue uses location exceptions, each check line follows the most specific rule: the location's exception for the product, then the location's exception for the category, then the product's rule, the category's rule, the location's own percent and finally the guest's level or the program percent. Each field (percent, earns, payable with cashback) comes from the first rule that sets it. Example: program 5%, category Alcohol 3%, at the Ciocana location Alcohol 2%. At Ciocana an alcohol line earns 2%, at other locations 3%, other products 5%. Exceptions apply only to checks whose register_id is bound to a location. Earning or redeeming switched off at a location and the location's redeem limit always apply. Read the exceptions with GET /v1/catalog/location-rules.
Cashback as payment or as discount
The venue's accountant picks in Developers → Register rules how the till books a cashback payment. As payment (default): cashback is a tender, one sum next to cash and card; the item prices and VAT do not change. As discount: cashback lowers the item prices and VAT is taken from the price after the discount. In that mode every line of POST /v1/checks/calculate and POST /v1/transactions also has redeem_allocated (minor units): the part of redeem_amount that falls on the line, in proportion to the line amount. Lines that cannot be paid with cashback get 0, and the lines always add up to redeem_amount exactly (the leftover cents go to the largest line). The mode is in settings.redeem_accounting of GET /v1/account (payment or discount). Without line_items nothing is split.
{
"amount": 10000,
"redeem_amount": 1000,
"net_amount": 9000,
"line_items": [
{ "sku": "LATTE", "amount": 6000, "redeemable": true, "redeem_allocated": 600 },
{ "sku": "CAKE", "amount": 3000, "redeemable": true, "redeem_allocated": 300 },
{ "sku": "WATER", "amount": 1000, "redeemable": true, "redeem_allocated": 100 }
]
}Discount types
Send the discount the till applied as discount_type, a code of up to 64 characters such as employee, discount_card or promo, on the check and, if needed, on single lines (line_items[].discount_type). Each new code appears by itself in Developers → Discount types, where the owner names it and decides whether such a check earns cashback and whether it can be paid with cashback. New types earn and redeem until the owner changes them. A check type that earns nothing gives 0 cashback for the whole check; a line type that earns nothing gives 0 for that line only. Where paying with cashback is not allowed, POST /v1/checks/calculate answers max_redeem: 0 with limited_by: "discount_type" and redeem_blocked_reason: "discount_redeem_not_allowed", and POST /v1/transactions with redeem_amount or hold_id is refused with 400 discount_redeem_not_allowed. Answers then also carry discount_type (the type and its rules) and each line its own discount_type. Venues that did not turn discount types on can send the field: it is ignored.
Items on promotion
Mark a check line as an item on promotion with line_items[].promo: true on POST /v1/checks/calculate, POST /v1/transactions and POST /v1/holds. The owner sets two rules for such lines in Developers → Register rules → Items on promotion: earn cashback (on by default) and pay with cashback (off by default). A rule that is off beats every product, category and location rule for that line: the line earns nothing (earn_percent: null, cashback_earned: 0) or cannot be paid with cashback (redeemable: false). A rule that is on changes nothing, the line follows its usual rules. The part of the check that may be paid with cashback, max_redeem and, with redeem as discount, redeem_allocated leave promo lines out, so spread the cashback over the lines with redeemable: true only. Every line of the answer then carries promo (true or false), the check stores it, and GET /v1/account returns the rules in settings.promo_earn and settings.promo_redeem. A value other than true, false or null answers 400 parameter_invalid. A refund follows what the original line did, so promo is not needed there. Venues without this rule can send the field: it is ignored.
{
"member": "2000111703779",
"amount": 10000,
"line_items": [
{ "sku": "4840001", "name": "Corona 0.33", "quantity": 2, "unit_price": 3500, "promo": true },
{ "sku": "2040", "name": "Paine", "quantity": 1, "unit_price": 3000 }
]
}{
"object": "check_calculation",
"amount": 10000,
"max_redeem": 900,
"cashback_earned": 500,
"earn_rate": 5,
"line_items": [
{ "sku": "4840001", "amount": 7000, "earn_percent": 5, "cashback_earned": 350, "redeemable": false, "promo": true },
{ "sku": "2040", "amount": 3000, "earn_percent": 5, "cashback_earned": 150, "redeemable": true, "promo": false }
],
...
}Gifts waiting to be handed out
The owner sets gift rules on the Gifts page: a gift for total purchases (for example 5000 MDL, a bottle of wine) or for reaching a cashback level. When a check crosses the threshold or moves the guest to that level, the gift opens and waits for the guest. Each guest gets one gift per rule, ever; several thresholds crossed by one check open several gifts. Guests who were past the threshold before the rule was switched on get nothing, and a refund does not take the gift back. A gift may have a waiting period; after it the gift is expired.
Flow for the till: 1) POST /v1/checks/calculate answers gifts.pending (already waiting) and gifts.unlocks (what this check will open, with id: null), and the first line of display.cashier_text is the gift, so show it to the cashier. 2) POST /v1/transactions answers gifts.unlocked (opened by this check, with ids) and gifts.pending. 3) The cashier hands the gift out and presses Gift handed out: call POST /v1/members/{member}/gifts/{gift_id}/give. The member object also carries gifts.pending. Events gift.unlocked and gift.given are sent. Venues without gifts never get the gifts field, and the gift endpoints answer 404 endpoint_not_found.
{
"object": "check_calculation",
"amount": 120000,
"cashback_earned": 6000,
"gifts": {
"pending": [],
"unlocks": [
{ "object": "gift", "id": null, "title": "Bottle of wine", "source": "spend_threshold", "threshold": 500000, "level": null, "cashier_note": "From the shelf by the till", "status": "pending", "expires_at": "2026-12-16T10:00:00.000Z" }
]
},
"display": {
"cashier_text": "Gift: Bottle of wine (hand it to the guest) · Cashback earned: 60.00 MDL · Cashback balance: 210.00 MDL",
"receipt_lines": ["Gift: Bottle of wine (hand it to the guest)", "Cashback earned: 60.00 MDL", "..."]
},
...
}"gifts": {
"unlocked": [
{ "object": "gift", "id": "6f1c0b7e-3a2d-4b8e-9c55-0d2e7a91f4b2", "title": "Bottle of wine", "source": "spend_threshold", "threshold": 500000, "level": null, "status": "pending", "unlocked_at": "2026-11-16T10:00:00.000Z", "expires_at": "2026-12-16T10:00:00.000Z", "given_at": null }
],
"pending": [ ... the same gift and any older ones still waiting ... ]
}curl -X POST https://loyaltyfy.io/api/v1/members/4285324286429/gifts/6f1c0b7e-3a2d-4b8e-9c55-0d2e7a91f4b2/give \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: give-6f1c0b7e" \
-H "Content-Type: application/json" \
-d '{ "register_id": "401", "cashier": "Ana" }'Stamp modes
By default a stamp program gives 1 stamp per check. The owner of a shop can change that on the Program page: 1 stamp per check that has an item from chosen categories, or 1 stamp for every unit of goods from chosen categories (a weighed item counts as one unit), plus a minimum check amount for a stamp. The categories are the category codes of your line_items or of your catalogue. The category modes need line_items on POST /v1/transactions and POST /v1/checks/calculate; a check without lines gives 1 stamp, and the minimum amount applies to every check. stamps_earned says how many stamps the check gave; when they pass the card's threshold more than once, several rewards unlock at once and calculate also answers rewards_unlocked. A void takes back exactly the stamps that are left. In the per unit mode a check can be returned by lines with POST /v1/transactions/{external_id}/refunds: the stamps for the returned units are taken back (from unused rewards if needed, never below zero) and the refund answers stamps_reversed. Other stamp checks are still refunded in full with a void. Venues without stamp modes keep 1 stamp per check.
Card must be scanned
With this rule a check, visit, hold or reward for a card is accepted only if the same key sent that card to POST /v1/scans shortly before. A card number typed by hand on the register is refused with scan_required. Send the scanner's raw output to /v1/scans, then go on as usual.
Manual adjustments
Off by default. When the owner allows it, a key with the members:adjust scope can add or take cashback with a reason, up to the limit the owner set per adjustment. Each one is in the member's history and sends balance.adjusted.
curl https://loyaltyfy.io/api/v1/members/2000111703779/adjustments \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "external_id": "ADJ-2026-0009", "amount": 2000, "reason": "Goodwill after a complaint" }'
# a negative amount takes cashback away