Skip to main content

Loyalty Flows

Read first: Overview and Concepts · General Requirements

The In-Store Loyalty API supports three loyalty flows, each the same two-step validate → close transaction: a validation call reserves the loyalty result when the customer is identified, and a close call makes it permanent once the order is paid. The flows are QR point accrual, QR reward redemption, and the phone number-based flow. This document describes them at the business level — what the customer, the cashier, and your POS each do and see; field-level detail lives in the In-Store Loyalty API specification and the capability guides that follow. Side-by-side qr-code + order-closed request/response examples for the accrual and reward-redemption flows are in the QR Code Loyalty Guide §7.

All loyalty arithmetic — which rewards apply, how many points an order earns — is computed entirely on the LoyaltyPlant side. Your integration never calculates points; it reports orders and applies what the in-store API returns.

1. QR point accrual​

The everyday flow: a customer earns points for a purchase.

Trigger (dual-surface). The customer opens the LoyaltyPlant mobile app and taps "Show loyalty card" to display a QR code (and a short numeric code). The transaction can then start from either surface: the customer scans their QR code at the self-service kiosk, or the cashier scans the customer's QR code at the cash register / POS terminal (typing the short numeric code by hand is the manual fallback on either surface).

Lifecycle — validate (reserve) → close (finalize). The moment the QR code is captured, your integration calls processQrCode (spec). The in-store API identifies the customer and returns everything that applies to the order, but the loyalty transaction is only reserved — no points are credited yet. When the order is paid and closed, your integration calls orderClosed (spec) with the final order contents; only now are the points credited to the customer.

The key point of the diagram: scanning only reserves the transaction — points are credited when the order is closed, not when the QR code is scanned.

What each party sees:

  • The customer sees the points arrive in the app after the order is closed — not at scan time.
  • The cashier (or, on a self-service kiosk, the customer) sees the human-readable messages from the validation response, e.g. "Purchase with loyalty card confirmed. Points will be added after the order is closed." Your POS or kiosk should display them.
  • The POS receives the customer's identity and, since 1.7, their loyalty tier and current points balance, which it can show to the customer or print on the receipt.

Two timing rules shape the experience: per the spec a QR code is short-lived (about 5 minutes after the customer opens it) and single-use, so the scan must happen while the customer is at the kiosk or the cash register. How many points an order earns is set by the brand's configured conversion rate, managed on the LoyaltyPlant side.

2. QR reward redemption​

The flow where points come back out: a customer spends points on a reward.

Trigger (dual-surface). The customer chooses a reward in the app and taps "Redeem" before coming to pay; the QR code they then show carries the selected reward. As with accrual, the QR code can be captured from either surface: the customer scans their QR code at the self-service kiosk, or the cashier scans the customer's QR code at the cash register / POS terminal.

Lifecycle — validate (reserve) → close (finalize). When your integration calls processQrCode (spec), the in-store API responds with the reward that must be added to the order — a reward menu item or a discount (e.g. "apply this 100% discount") — and the POS applies it. The redemption is only reserved at this point. When the order is closed with orderClosed (spec), the redeemed reward is deducted from the customer's account and the same closure also credits the points earned on the rest of the order.

Note: A single processQrCode validation does both jobs at once — it redeems the selected reward and accrues points for the rest of the order. The customer still earns points on the purchase automatically; closing the order credits those points alongside settling the redemption.

The key point of the diagram: the POS must actually apply what the in-store API returns — the reward is not "redeemed" until the closed order echoes it back.

What each party sees:

  • The customer sees the chosen reward added to the order and, after closure, the spent points deducted in the app.
  • The cashier (or, on a self-service kiosk, the customer) sees the reward item or discount the in-store API returned and a confirmation message; the reward never increases the order total.
  • The POS must add exactly the reward item or discount the validation response carries, then echo it back in the closed-order contents so the redemption settles correctly.

Business rules, at a high level:

  • A reward can be a menu item, a discount, or a top-up of bonus points — and it never increases the order total.
  • Alcohol and tobacco items cannot be given as rewards.
  • The validation response can also carry a points payment that reduces the amount the customer pays, per the brand's points-to-currency conversion rate.
  • If the customer changes their mind before the order is closed (e.g. drops a reward), the closure call lists only the rewards that were actually used — the in-store API automatically returns the rest to the customer's account.

3. Phone number-based flow​

The third flow needs no app and no QR code: the customer is identified by phone number. It is available since 1.6.

Trigger (dual-surface). The phone number is only requested after the order has been placed — never before the customer commits to the purchase — on either surface: the customer enters their number on the self-service kiosk, or the cashier enters it at the cash register / POS terminal. On a kiosk the prompt appears after the payment screen and before the success/order-number screen, with the points the order would earn shown as the incentive.

Lifecycle — validate (resolve-or-create) → close (finalize). This flow follows the same validate → close cycle as the QR flows, with one difference: the loyalty account is resolved or created at the validation step. When your integration sends the phone number to processQrCode (spec), the in-store API looks the number up — if a customer with that phone number already exists the points accrue to the existing account; if not, a new account is created on the spot. Either way the transaction is only reserved at validation, and orderClosed credits the points when the order is paid. A new customer then claims the points by verifying the number in the app. Account-resolution detail — how the auto-created account is later reconciled with the app profile — is covered in full in the Phone Number Guide.

The key point of the diagram: the same phone-number entry serves two outcomes — an existing customer accrues to the account they already use, or a brand-new account is created and credited on the spot.

What each party sees:

  • The customer — on the kiosk — is shown the points the order would earn before entering the number. If the customer is new (i.e. has not used the LoyaltyPlant app before), they claim those points by verifying the number in the app.
  • The cashier — at the cash register / POS terminal — asks for the phone number, enters it, and closes the order as usual; the in-store API decides whether the number resolves to an existing account or creates a new one.

Note: Entering a phone number is always optional for the customer. A customer who declines simply completes the order with no loyalty transaction.

4. Behaviors common to all flows​

The points below apply identically to all three flows.

A rejected validation still returns HTTP 200. A QR code or phone number can be refused at validation time — the code was generated for another partner, it has expired, it was already scanned, the order was already closed, and so on. The in-store API answers the processQrCode call with HTTP 200 and a body carrying accepted: false plus a human-readable messages[] entry. No loyalty transaction is reserved. The cashier must be shown the message text (e.g. "This QR code has already been scanned") and closes the order normally — the order always proceeds as an ordinary sale, and your POS must never block the sale on a loyalty rejection. The rejection codes (501–506 and the rest) and the recommended handling for each are catalogued in Message & Error Codes.

A missing orderClosed auto-annuls after a timeout. Every validation must end in either orderClosed or refundOrder. If orderClosed never arrives after a validation, the reserved transaction is annulled automatically after a timeout window: the customer's points are not credited, and any points the customer spent on redeemed rewards are returned to their account a short while later. The annul is performed by the LoyaltyPlant platform, not the in-store API; confirm the exact timeout with the LoyaltyPlant team for your deployment. This is a recovery safety net, not a normal path — customers notice missing points immediately, so treat a lost orderClosed as a serious defect.

All loyalty arithmetic happens on the LoyaltyPlant side. Which rewards apply and how many points an order earns are computed by the in-store API, never by your integration.

Note: Table-service scenarios, where an open order is tied to a table number, use a different LoyaltyPlant device-based integration that does not go through the in-store API. If that is your case, discuss it with the LoyaltyPlant team. See Overview and Concepts.

5. Refunds and corrections​

If an order is cancelled after it was closed, the integration reports the refund with refundOrder (spec), and the in-store API reverses the loyalty transaction: points credited for the order are taken back, and rewards the customer spent on it are restored to their account. A refund always reverses the whole order — partial refunds are not supported.

Corrections made while the order is still open need no refund at all: the closure call simply reports the final order contents, and the in-store API settles the difference (see 2. QR reward redemption).

Next: QR Code Loyalty Guide →