FideliaDevelopers · POS APIFrançais

At the till

Scanning

Fidelia cards show either a QR code (the card’s serial, 32 characters 0-9a-f) or a barcode (Code 128 of the 13-digit card number), as the shop chose in its card settings. Pass whatever the scanner read as {code}: the API accepts both, and so does the Fidelia scanner app.

  1. Scan → GET /cards/{code}. Show customer.first_name and a short summary of the card (see the table below).
  2. Membership: if membership.active, apply membership.discount_percent to the basket. If not, offer Renew (POST …/membership/renew) or tell the customer it expired.
  3. Rewards: if rewards_available isn’t empty, ask “Use reward now?” (a stamp card can have smaller rewards on the way, milestones, with ids milestone:<id>; the card keeps collecting after one). On yes, POST …/rewards/{id}/redeem and add product.ref to the receipt at no charge (product.value is its normal price, for your reports). If the shop didn’t link a product, product is null: let the cashier pick the item.
  4. Balance: for cashback and prepaid, offer Pay with card balance: POST …/balance/spend with "amount": "all" (or a typed amount) and receipt_total. Add spent as a payment line; the customer pays the rest another way.
  5. Close the receipt → POST …/sale with the total actually paid and the receipt number. Send it even when nothing seems to apply: Fidelia decides.

Use the same receipt_ref for every call of one receipt: refunds and the cashback calculation rely on it.

What a card looks like

type Show Fields
stamps “7 / 10 stamps” stamps.count, stamps.required, stamps.reward_ready, stamps.reward, stamps.milestones[]
points “120 points” points.balance, points.rewards[] with available
cashback “Balance 5.00” balance.amount, balance.percent
prepaid “Balance 22.00” balance.amount, balance.bonus_percent
membership “Member · 10 % off” membership.active, discount_percent, valid_until, perk
pack “8 coffees left” pack.items_left, pack.active, pack.item

Every card may also have a VIP level in tier (name and perk).

The sale

POST /cards/{code}/sale
{ "amount": 1250, "receipt_ref": "T1-000042" }

What Fidelia does, per type and per the shop’s till settings:

Type Effect
stamps +1 stamp if automatic stamps are on and amount reaches the shop’s minimum. A full card becomes reward_ready.
points earned_points = amount ÷ the program’s spend_per_point. reward_available names a reward that just became available.
cashback earned_balance = percent of the amount minus the balance spent on the same receipt.
membership A check-in (a visit), if the membership is active.
prepaid, pack Nothing (not_applicable).

A sale never fails because of the card’s state. It answers 200 with "applied": false and a reason:

reason Meaning
cooldown A stamp / check-in was given a few minutes ago (shop setting).
reward_ready The stamp card is full: redeem the reward first, then stamps start again.
below_min_amount Below the shop’s minimum receipt for a stamp.
auto_stamp_off The shop stamps by hand, not on every sale.
nothing_to_earn Everything was paid with the card balance, or the amount was 0.
membership_expired, membership_inactive Not an active member.
not_applicable Prepaid and pack cards earn nothing on a sale.
program_inactive, subscription_inactive The card or the shop’s subscription stopped; nothing to do at the till.

Other actions

Call For Body
POST …/rewards/ready/redeem full stamp card also_stamp: true also stamps today’s visit
POST …/rewards/milestone:<id>/redeem stamp card milestone once per round of stamps; already_claimed after
POST …/rewards/{id}/redeem points id from points.rewards[]
POST …/balance/spend cashback, prepaid amount (or "all"), receipt_total
POST …/balance/topup prepaid amount paid; credited includes the bonus
POST …/membership/renew membership renews, or activates a membership waiting for payment
POST …/pack/sell pack activates a waiting pack, or adds count packs
POST …/pack/use pack count items (1–10)

Every answer returns the updated card, so the till can show the new state right away.