☰ Menu · POS and cash registers
Guides

POS and cash registers

Everything a till needs: find the guest, apply the check, redeem cashback, handle refunds, and issue cards that carry the till's own numbers.

The usual flow at the counter: the cashier scans the guest's wallet card (or types the phone), the till shows the balance, the guest decides whether to pay part of the check with cashback, the check closes and the till sends it to us. The guest's card on the phone updates within seconds.

1. Find the guest

GET /v1/members/{member} accepts whatever the till has: the card number, the barcode content, the phone in international format, or our member id. URL-encode a phone (+ becomes %2B).

curl
# by the number on the card (or the barcode the scanner read)
curl https://loyaltyfy.io/api/v1/members/2000111703779 \
  -H "Authorization: Bearer sk_test_..."

# by phone, with fresh add-to-wallet links
curl "https://loyaltyfy.io/api/v1/members/%2B37366791102?expand=wallet" \
  -H "Authorization: Bearer sk_test_..."

Show the cashier what matters for the program, from the member object:

program.mechanicShow
cashbackcashback.available and the most that can be redeemed: the smaller of the balance and redeem_max_percent of the check.
stampsstamps.current of stamps.required, and stamps.rewards_available if the guest has a free item waiting.
visit_discount, vipdiscount.percent and discount.tier: apply this discount to the check yourself.

2. What the card's barcode contains

The venue chooses the barcode format in Developers → Card barcode, so it matches what the till's scanner reads:

FormatThe barcode containsUse when
QR with the card numbercard_number, for example 2000111703779The scanner reads QR and the till searches by card number. Recommended.
Barcode (Code 128) with the card numberThe same number as a linear barcode, printed under the barsOlder laser scanners that cannot read QR.
QR, Loyaltyfy cashier appOur internal serial (a UUID)The default. Only the Loyaltyfy cashier app reads it; a POS can still find the guest by phone.

Changing the format updates the cards already in guests' wallets; no one needs to reinstall anything. Whatever the format, send the scanned value as is to GET /v1/members/{member} or to POST /v1/scans, which also strips scanner prefixes and line breaks.

3. Issue cards with the till's own numbers

If the till already has a card system, keep its numbers. Enrol the guest with card_number set to the till's number; the wallet card shows that number and its barcode encodes it, so the scanner finds the guest in the till's own database too. Numbers are unique per venue: a duplicate gets 409 card_number_taken. To give an existing member a till number later, use PATCH /v1/members/{member} with card_number.

curl
curl https://loyaltyfy.io/api/v1/members \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d1b2c4e-enrol-000123" \
  -d '{
    "phone": "+37366791102",
    "first_name": "Ion",
    "last_name": "Popescu",
    "card_number": "2000111703779",
    "language": "ro",
    "consent": true
  }'

The response has wallet.apple_url and wallet.google_url. Print them as a QR on the receipt, send them by SMS, or show them on the customer display: the guest opens the link and the card is added to the phone.

4. Apply the check

Send each closed check once, after payment. amount is the full check before any cashback; redeem_amount is how much of it the guest paid with cashback. We apply the program's rules (minimum check, redeem cap, tiers) the same way the venue's cashier screen does.

curl
curl https://loyaltyfy.io/api/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "CHK-2026-000123",
    "member": "2000111703779",
    "amount": 25000,
    "currency": "MDL",
    "register_id": "POS-1",
    "store_id": "S-1",
    "closed_at": "2026-10-06T18:17:00+03:00",
    "line_items": [
      { "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee" },
      { "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts" }
    ]
  }'
Response · 201
{
  "object": "transaction",
  "id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
  "external_id": "CHK-2026-000123",
  "status": "completed",
  "amount": 25000,
  "redeem_amount": 0,
  "cashback_earned": 1250,
  "stamps_earned": 0,
  "reward_unlocked": false,
  "net_amount": 25000,
  "currency": "MDL",
  "register_id": "POS-1",
  "closed_at": "2026-10-06T15:17:00+00:00",
  "livemode": false,
  "created_at": "2026-10-06T18:17:17.921+00:00",
  "voided_at": null,
  "amount_refunded": 0,
  "line_items": [
    { "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee", "amount": 8000, "earn_percent": 5, "cashback_earned": 400, "redeemable": true, "quantity_refunded": 0 },
    { "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts", "amount": 17000, "earn_percent": 5, "cashback_earned": 850, "redeemable": true, "quantity_refunded": 0 }
  ],
  "member": {
    "object": "member",
    "id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
    "card_number": "2000111703779",
    "cashback": { "balance": 1250, "currency": "MDL", "earn_rate": 5, ... },
    ...
  }
}
external_id must be unique across all tills of the venue. If check numbers restart on each till or each shift, combine them, for example POS-3-000123 (till 3, check 123).

Cashback is earned on what the guest actually paid: amount − redeem_amount. For stamp and visit programs the check counts as a visit; stamps_earned and reward_unlocked tell you what happened, so the till can say "one more coffee and the next is free".

If the owner turned on the rule "in one visit the guest either earns or redeems", a check that redeems (redeem_amount above 0, or a hold_id) earns no cashback: cashback_earned is 0, every line has cashback_earned 0 and earn_percent null, and the response of POST /v1/checks/calculate and POST /v1/transactions carries earn_blocked: "redeemed". The visit still counts (visits, spend, levels). The next check without a redemption earns as usual. Without the rule there is no earn_blocked field.

5. Pay with cashback

Ask for the balance first, let the guest choose, then send the check with redeem_amount. If the balance changed in between (the guest paid somewhere else a second ago), you get 402 insufficient_balance with the current available amount; show it and let the cashier retry.

curl
curl https://loyaltyfy.io/api/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "CHK-2026-000124",
    "member": "2000111703779",
    "amount": 12000,
    "redeem_amount": 1250
  }'
Response · 402
{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "message": "redeem_amount is more than the available balance.",
    "param": "redeem_amount",
    "available": 1250
  },
  "request_id": "req_6f4c30b8ca7d4423a9d4"
}
Give the cashback discount only after we answered 201 or 200. Send the check when its total is final but before taking payment. If there is no answer, retry with the same external_id, or close the check without cashback. Otherwise the guest can get the discount and keep the balance.

6. Give a stamp reward

When stamps.rewards_available is above zero the guest has a free item. Give it on the till and record it:

curl
curl -X POST https://loyaltyfy.io/api/v1/members/4285324286429/rewards/redeem \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: reward-4285324286429-0001"

7. Refunds and mistakes

Void a check in full by its external_id: earned cashback or stamps are taken back, redeemed cashback is returned to the guest. For a partial return send POST /v1/transactions/{external_id}/refunds with either the returned amount or the returned line_items (sku and quantity): by lines, cashback follows what each line really earned, so returning one item out of three takes back exactly that item's cashback. A voided or fully refunded check no longer counts as a visit or spend, so returns never raise the guest's level. A till that has a «return item» button maps it to POST /v1/transactions/{external_id}/returns with the returned lines.

curl
# the guest returns 50.00 of a 200.00 check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000124/refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000017", "amount": 5000 }'

# or: the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000018", "line_items": [{ "sku": "1001", "quantity": 1 }] }'

# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back
curl
curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
  -H "Authorization: Bearer sk_test_..."

8. When the till is offline

Queue checks locally with their external_id and closed_at and send them when the connection is back. Duplicates are ignored, so it is safe to resend the whole queue. Lookups need the network; if it is down, let the cashier skip loyalty for that check rather than block the sale.

Wait for our answer 3 to 5 seconds. If it does not come, close the check without loyalty and put it in the queue; it earns later when the queue is sent. Behave the same way if the outage is on our side: a slow or failed answer from us must never hold up the sale. Redeeming cashback without our answer is not allowed: offline we cannot see the balance, and two venues could spend the same money at once.

If the venue has set offline rules in Developers → Register rules, GET /v1/account returns them in settings: timeout_seconds (how long to wait, 2 to 30, default 5), offline_redeem (always false) and offline_max_hours (how late a queued check may still arrive; we recommend 72).

JSON
"settings": {
  "offline_max_hours": 72,
  "timeout_seconds": 5,
  "offline_redeem": false
}

Checks pushed from the till's server

Some POS systems cannot call an API at the counter but can send closed checks from their server. That works too: send the same POST /v1/transactions from the server, with the card number the cashier scanned, as soon as the check is closed. Subscribe to transaction.completed if the till wants to show the result later.

Questions about an integration: api@loyaltyfy.io. We answer within one business day.