Skip to content
revisit
Start today
LoyaltyEarn and redeem

Loyalty

Earn and redeem

Earn, redeem, renew, top up and spend, once per order.

Pilotv1

One call earns, redeems, renews, tops up or spends for one of your orders or services. sourceEventId is your id for that order: it makes the action happen once for good, even when a retry comes under a new Idempotency-Key or after the operation record expired. The answer to a repeat is the original one with duplicate: true.

The action runs the program's own rules (stamps per visit, points per taka, the reward list, the plan and scan metering) and lands in the same balance and history the counter, the wallet and the customer's card page read.

Paths are relative to https://app.revisit.cards/v1/developer.

Endpoints

Earn, redeem, renew, top up or spend for one order or service

POST/programs/{id}/actions

Scopeloyalty:write

Requires loyalty:write and an Idempotency-Key. action is earn, redeem, renew (Subscription programs, where a redeem uses one included use), earn with amount (the bill, minor units) and redeem with amount (credit used) on Cashback programs (both need currency, the program's; the cashback is amount x percent / 100 rounded half up once, in minor units), topup or spend (Prepaid programs: amount is a whole number of the currency's minor unit and currency must be the program's, else 422 CURRENCY_MISMATCH; there is no conversion); sourceEventId is your id for the order or service and makes the action happen once, even when a retry comes under a new Idempotency-Key, after the operation records expired, or under a rotated key (the answer is the original one with duplicate: true). The same id with different content is 409 SOURCE_EVENT_CONFLICT. The action runs the program's own rules (stamps per visit, points per taka, the reward list, the plan and scan metering) and lands in the same balance and history the merchant app, wallet and customer page read; a balance the card cannot cover, a full card or a plan refusal is 409 or 403 with a card rule code and changes nothing. Stamp programs have one reward (omit it); Points programs need rewardId or an exact rewardName. void, adjust, set_balance and any balance or delta field are 422 UNSUPPORTED_ACTION, as is topup or spend on a program that is not Prepaid and earn or redeem on one that is. A spend over the balance is 409 INSUFFICIENT_CREDIT; an amount over the per-operation cap is 422 INVALID_AMOUNT; a top-up or cashback earn past the balance limit is 409 BALANCE_LIMIT; a bill too small to earn any cashback is 400 INVALID_AMOUNT. The customer is named by externalCustomerId (enroll or link first); unknown customers and programs outside the key's limits are 404.

Send an Idempotency-Key header. Safe to retry.

Path

iduuidRequired

Body

actionenumRequired
One of earn, redeem, renew, topup, spend.
externalCustomerIdstringRequired
sourceEventIdstringRequired
Your id for the order or service. It makes the action happen once.
branchIduuid
quantityinteger
Stamp programs. Stamps for this order, within the card's per-visit limit (1 when omitted).
amountinteger
Points and Points and tiers programs. The order total in whole taka (leave out on a per-visit rule and on Tiered; Tiered counts one visit per earn), turned into points by the program's rule. On a Cashback program it is the bill in the currency's minor unit and currency is required.
currencyenum
ISO 4217. Fixed per program once money has moved. Minor-unit digits are 0 for JPY, KRW and VND, 3 for BHD, JOD, KWD and OMR, else 2. One of AED, BDT, BHD, EUR, GBP, INR, JOD, JPY, KRW, KWD, MYR, OMR, SGD, USD, VND.
rewardIdstring
A Points reward's id. Omit on a Stamp program; a Subscription program has no rewards (a redeem uses one included use), so leave both out.
rewardNamestring
Or the exact reward name. Send one of the two.

Returns 200

actionenumRequired
One of earn, redeem, renew, topup, spend.
balanceintegerRequired
The balance after this action (a next-card bonus stamp included).
customerIdstringRequired
deltaintegerRequired
Signed change to the balance.
duplicatebooleanRequired
True when this source event was already applied; nothing changed and this is the original result.
externalCustomerIdstringRequired
membershipIdstringRequired
programIdstringRequired
lifetimeinteger
Tiered and Points and tiers only. Lifetime visits or points after this action; it never falls (balance does on a redeem), and tiers follow it.
tierobject or null
Tiered and Points and tiers only. The tier held after this action (null before the first), from the rules as they were when the action ran.
tier.namestringRequired
Each tier needs a different name. 2 to 20 characters.
tier.thresholdintegerRequired
Reached when lifetime visits (Tiered) or lifetime points (Points and tiers) hit this number. Each tier needs a higher number than the one before.
tier.perkstringRequired
tier.bonusPercentintegerRequired
Points and tiers only - extra points on every earn while in this tier. Use 0 on Tiered. 0 to 100.
nextTierobject or null
Tiered and Points and tiers only. The next tier and the lifetime left to reach it; null at the top.
nextTier.namestringRequired
Each tier needs a different name. 2 to 20 characters.
nextTier.thresholdintegerRequired
Reached when lifetime visits (Tiered) or lifetime points (Points and tiers) hit this number. Each tier needs a higher number than the one before.
nextTier.perkstringRequired
nextTier.bonusPercentintegerRequired
Points and tiers only - extra points on every earn while in this tier. Use 0 on Tiered. 0 to 100.
nextTier.remainingintegerRequired
percentinteger
Cashback only. The percent given back, from the rule as it was when the action ran.
currencystring
Prepaid and Cashback. The program's currency from the rule as it was when the action ran; balance, delta and amount are minor units of it.
amountinteger
Prepaid and Cashback. The size of this top-up or spend (Cashback earn - the bill; redeem - the credit used), always positive.
usesLeftinteger
Subscription only. Included uses still left this period (the same number as balance).
includedUsesinteger
Subscription only. The uses each period includes, from the rule as it was when the action ran.
periodEndsAtdate-time or null
Subscription only. When the running period ends, as it stood after this action. Null before the first renewal.
rewardNamestring or nullRequired
sourceEventIdstringRequired
transactionIdstringRequired
The ledger row, the same one the merchant app shows in the customer's history.

Errors

  • 422CURRENCY_MISMATCHa money action named a currency other than the program's. Nothing changed.
  • 409SOURCE_EVENT_CONFLICTthis source event id was already applied with different content (another customer, program, action or amount). Nothing changed.
  • 422UNSUPPORTED_ACTIONthe action is not one a service may take (top-up, spend, set or adjust a balance, void) or the program's card type does not take earning and redeeming from the API yet. Nothing changed.
  • 409INSUFFICIENT_CREDIT
  • 422INVALID_AMOUNT
  • 409BALANCE_LIMIT
Request
curl -X POST "https://app.revisit.cards/v1/developer/programs/e01b010d-2c65-48e1-83a0-acad79f8d3b4/actions" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-7b1d-4c3e-9a6f-0d4b8e36983a" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "earn",
    "externalCustomerId": "user-42",
    "sourceEventId": "order-1001"
  }'
Response
{
  "data": {
    "action": "earn",
    "balance": 7,
    "customerId": "eb83b9c0-5619-432d-b857-cef7fcf84edb",
    "delta": 1,
    "duplicate": false,
    "externalCustomerId": "user-42",
    "membershipId": "b53ca741-1e76-4ddb-b6a5-998b65c4aff3",
    "programId": "d7595bbd-4342-41b4-9037-2e61a9f8403f",
    "rewardName": "Free chai",
    "sourceEventId": "order-1001",
    "transactionId": "add73925-4de9-412c-8cc2-582b074074ca"
  },
  "requestId": "be67afca-94da-4818-b383-fa87bc212acf",
  "success": true
}