LoyaltyPrograms

Loyalty

Programs

Create, configure, move and delete loyalty programs.

Pilotv1

A program is one of the shop's loyalty cards: Stamp, Points, Tiered, Points and tiers, Subscription, Prepaid or Cashback. You create and change it with the same rule shapes the merchant app's card editor uses, so a program made here looks and behaves exactly like one made in the app.

Prepaid and Cashback programs hold money in one currency, as whole minor units (1250 is 12.50 BDT). There is no conversion: a different currency is 422 CURRENCY_MISMATCH.

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

Endpoints

GET/programs
List the business's loyalty programs
POST/programs
Create a Stamp, Points, Tiered, Points and tiers, Subscription, Prepaid or Cashback program
GET/programs/{id}
Read one program
PATCH/programs/{id}
Change a program's label, colour or rules
DELETE/programs/{id}
Delete a program nobody has joined
PUT/programs/{id}/branches
Choose where a chain program is honoured
POST/programs/{id}/promote
Make a branch program a chain-wide program

List the business's loyalty programs

GET/programs

Scopeprograms:read

Requires the programs:read scope.

Request

curl "https://app.revisit.cards/v1/developer/programs" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY"

Response

{
  "data": [
    {
      "branchIds": [
        "b703a365-4444-483c-a078-fa042c813757"
      ],
      "cardColor": "#1F2937",
      "cardType": "stamp",
      "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
      "memberCount": 12,
      "name": "Chai card",
      "ownerBranchId": "21132f65-97fe-438b-8f09-6910b9e227c0",
      "rewardName": "Free chai",
      "settings": {
        "maxStampsPerVisit": 1,
        "nextCardBonus": false,
        "selfStamp": false,
        "stampsRequired": 3,
        "uniqueQr": false,
        "welcomeStamps": 3
      },
      "suspended": false
    }
  ],
  "requestId": "d49db77f-3b7b-4487-a910-e7d5c44b5d9b",
  "success": true
}

Create a Stamp, Points, Tiered, Points and tiers, Subscription, Prepaid or Cashback program

POST/programs

Scopeprograms:write

Requires programs:write and an Idempotency-Key. A key limited to specific programs cannot create programs; a key limited to branches places the program only on them. Answers 201 with the program.

Send an Idempotency-Key header. Safe to retry.

Body

cardTypeenumRequired: One of stamp, points, tiered, points_tier, subscription, prepaid, cashback.
namestring: The card label. Default empty (the reward is shown).
cardColorstring: #rrggbb; default #3b2a20
rewardNamestring: 2 to 40 characters.
stampsRequiredinteger: 3 to 20.
maxStampsPerVisitinteger: 1 to 5.
welcomeStampsinteger: 0 to 3.
nextCardBonusboolean
selfStampboolean
uniqueQrboolean
branchIdsuuid[]: Chain program honoured here; default every open branch the key may use.
ownerBranchIduuid: Makes it a branch program.
earnRuleobject
earnRule.modeenumRequired: One of per_visit, per_taka.
earnRule.pointsintegerRequired
earnRule.perTakainteger
rewardsobject[]
rewards[].namestringRequired: 2 to 40 characters.
rewards[].costintegerRequired: Each reward needs a different cost.

Returns 201

idstringRequired
namestringRequired: The merchant's label; empty means "use the reward".
cardTypestringRequired: stamp, points, cashback, prepaid, tiered, subscription, points_tier
cardColorstringRequired: #rrggbb
rewardNamestringRequired
branchIdsstring[]Required
ownerBranchIdstring or nullRequired
memberCountintegerRequired: Customers holding the program; any blocks deletion.
settingsobject or nullRequired: The rules of a Stamp, Points, Tiered or Points and tiers program; null for other types (not configurable through the API yet).
settings.stampsRequiredinteger: 3 to 20.
settings.maxStampsPerVisitinteger: 1 to 5.
settings.welcomeStampsinteger: 0 to 3.
settings.nextCardBonusboolean
settings.selfStampboolean
settings.uniqueQrboolean
settings.earnRuleobject
settings.earnRule.modeenumRequired: One of per_visit, per_taka.
settings.earnRule.pointsintegerRequired
settings.earnRule.perTakainteger
settings.rewardsobject[]
settings.rewards[].namestringRequired: 2 to 40 characters.
settings.rewards[].costintegerRequired: Each reward needs a different cost.
settings.minorUnitDigitsinteger: Digits after the decimal point of one major unit: 2 for USD (1250 is 12.50), 0 for JPY, 3 for KWD. A program made before currencies existed reads BDT.
suspendedbooleanRequired

Request

curl -X POST "https://app.revisit.cards/v1/developer/programs" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-7b1d-4c3e-9a6f-0d4b8e6b74e9" \
  -H "Content-Type: application/json" \
  -d '{
    "cardType": "stamp",
    "rewardName": "Free chai",
    "stampsRequired": 3
  }'

Response

{
  "data": {
    "branchIds": [
      "b703a365-4444-483c-a078-fa042c813757"
    ],
    "cardColor": "#1F2937",
    "cardType": "stamp",
    "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
    "memberCount": 12,
    "name": "Chai card",
    "ownerBranchId": "21132f65-97fe-438b-8f09-6910b9e227c0",
    "rewardName": "Free chai",
    "settings": {
      "maxStampsPerVisit": 1,
      "nextCardBonus": false,
      "selfStamp": false,
      "stampsRequired": 3,
      "uniqueQr": false,
      "welcomeStamps": 3
    },
    "suspended": false
  },
  "requestId": "a76e6503-89bb-4a71-adce-0ab0fd2aefb3",
  "success": true
}

Read one program

GET/programs/{id}

Scopeprograms:read

Requires the programs:read scope. An unknown, malformed or other business's id answers 404.

Path

iduuidRequired

Returns 200

idstringRequired
namestringRequired: The merchant's label; empty means "use the reward".
cardTypestringRequired: stamp, points, cashback, prepaid, tiered, subscription, points_tier
cardColorstringRequired: #rrggbb
rewardNamestringRequired
branchIdsstring[]Required
ownerBranchIdstring or nullRequired
memberCountintegerRequired: Customers holding the program; any blocks deletion.
settingsobject or nullRequired: The rules of a Stamp, Points, Tiered or Points and tiers program; null for other types (not configurable through the API yet).
settings.stampsRequiredinteger: 3 to 20.
settings.maxStampsPerVisitinteger: 1 to 5.
settings.welcomeStampsinteger: 0 to 3.
settings.nextCardBonusboolean
settings.selfStampboolean
settings.uniqueQrboolean
settings.earnRuleobject
settings.earnRule.modeenumRequired: One of per_visit, per_taka.
settings.earnRule.pointsintegerRequired
settings.earnRule.perTakainteger
settings.rewardsobject[]
settings.rewards[].namestringRequired: 2 to 40 characters.
settings.rewards[].costintegerRequired: Each reward needs a different cost.
settings.minorUnitDigitsinteger: Digits after the decimal point of one major unit: 2 for USD (1250 is 12.50), 0 for JPY, 3 for KWD. A program made before currencies existed reads BDT.
suspendedbooleanRequired

Request

curl "https://app.revisit.cards/v1/developer/programs/e01b010d-2c65-48e1-83a0-acad79f8d3b4" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY"

Response

{
  "data": {
    "branchIds": [
      "b703a365-4444-483c-a078-fa042c813757"
    ],
    "cardColor": "#1F2937",
    "cardType": "stamp",
    "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
    "memberCount": 12,
    "name": "Chai card",
    "ownerBranchId": "21132f65-97fe-438b-8f09-6910b9e227c0",
    "rewardName": "Free chai",
    "settings": {
      "maxStampsPerVisit": 1,
      "nextCardBonus": false,
      "selfStamp": false,
      "stampsRequired": 3,
      "uniqueQr": false,
      "welcomeStamps": 3
    },
    "suspended": false
  },
  "requestId": "b1330f0f-2a2c-4856-9914-7b14366a59f6",
  "success": true
}

Change a program's label, colour or rules

PATCH/programs/{id}

Scopeprograms:write

Requires programs:write and an Idempotency-Key. Send only what changes. A field that belongs to the other type (earnRule on a Stamp program) is a 422; the card type cannot change.

Send an Idempotency-Key header. Safe to retry.

Path

iduuidRequired

Body

namestring
cardColorstring
rewardNamestring
stampsRequiredinteger
maxStampsPerVisitinteger
welcomeStampsinteger
nextCardBonusboolean
selfStampboolean
uniqueQrboolean
earnRuleobject
earnRule.modeenumRequired: One of tiered, points_tier, subscription, prepaid, cashback.
earnRule.pointsinteger
earnRule.perTakainteger
earnRule.tiersobject[]
earnRule.tiers[].namestringRequired: Each tier needs a different name. 2 to 20 characters.
earnRule.tiers[].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.
earnRule.tiers[].perkstringRequired
earnRule.tiers[].bonusPercentintegerRequired: Points and tiers only - extra points on every earn while in this tier. Use 0 on Tiered. 0 to 100.
earnRule.earnobject
earnRule.earn.modeenumRequired: One of per_visit, per_taka.
earnRule.earn.pointsintegerRequired
earnRule.earn.perTakainteger
earnRule.planNamestring: The program's own plan name for its customers (not the business's Revisit billing). 2 to 30 characters.
earnRule.includedUsesinteger: Uses each period includes. 1 to 60.
earnRule.usesLabelstring: What a use is called, e.g. coffees. 2 to 20 characters.
earnRule.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.
earnRule.percentinteger: 1 to 50.
rewardsobject[]
rewards[].namestringRequired: 2 to 40 characters.
rewards[].costintegerRequired: Each reward needs a different cost.

Returns 200

idstringRequired
namestringRequired: The merchant's label; empty means "use the reward".
cardTypestringRequired: stamp, points, cashback, prepaid, tiered, subscription, points_tier
cardColorstringRequired: #rrggbb
rewardNamestringRequired
branchIdsstring[]Required
ownerBranchIdstring or nullRequired
memberCountintegerRequired: Customers holding the program; any blocks deletion.
settingsobject or nullRequired: The rules of a Stamp, Points, Tiered or Points and tiers program; null for other types (not configurable through the API yet).
settings.stampsRequiredinteger: 3 to 20.
settings.maxStampsPerVisitinteger: 1 to 5.
settings.welcomeStampsinteger: 0 to 3.
settings.nextCardBonusboolean
settings.selfStampboolean
settings.uniqueQrboolean
settings.earnRuleobject
settings.earnRule.modeenumRequired: One of per_visit, per_taka.
settings.earnRule.pointsintegerRequired
settings.earnRule.perTakainteger
settings.rewardsobject[]
settings.rewards[].namestringRequired: 2 to 40 characters.
settings.rewards[].costintegerRequired: Each reward needs a different cost.
settings.minorUnitDigitsinteger: Digits after the decimal point of one major unit: 2 for USD (1250 is 12.50), 0 for JPY, 3 for KWD. A program made before currencies existed reads BDT.
suspendedbooleanRequired

Request

curl -X PATCH "https://app.revisit.cards/v1/developer/programs/e01b010d-2c65-48e1-83a0-acad79f8d3b4" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-7b1d-4c3e-9a6f-0d4b8e07cea8" \
  -H "Content-Type: application/json" \
  -d '{
    "cardColor": "#1F2937",
    "name": "Chai card"
  }'

Response

{
  "data": {
    "branchIds": [
      "b703a365-4444-483c-a078-fa042c813757"
    ],
    "cardColor": "#1F2937",
    "cardType": "stamp",
    "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
    "memberCount": 12,
    "name": "Chai card",
    "ownerBranchId": "21132f65-97fe-438b-8f09-6910b9e227c0",
    "rewardName": "Free chai",
    "settings": {
      "maxStampsPerVisit": 1,
      "nextCardBonus": false,
      "selfStamp": false,
      "stampsRequired": 3,
      "uniqueQr": false,
      "welcomeStamps": 3
    },
    "suspended": false
  },
  "requestId": "8b0c2b11-916f-4248-a25d-fe3856817335",
  "success": true
}

Delete a program nobody has joined

DELETE/programs/{id}

Scopeprograms:write

Requires programs:write and an Idempotency-Key. A program with customers answers 409 CARD_HAS_CUSTOMERS, the last program 409 LAST_CARD.

Send an Idempotency-Key header. Safe to retry.

Path

iduuidRequired

Returns 200

idstringRequired
deletedtrueRequired

Errors

409CARD_HAS_CUSTOMERS
409LAST_CARD

Request

curl -X DELETE "https://app.revisit.cards/v1/developer/programs/e01b010d-2c65-48e1-83a0-acad79f8d3b4" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-7b1d-4c3e-9a6f-0d4b8ee9d635"

Response

{
  "data": {
    "deleted": true,
    "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c"
  },
  "requestId": "b0641722-552c-4936-8a67-54eff8f3ed4a",
  "success": true
}

Choose where a chain program is honoured

PUT/programs/{id}/branches

Scopeprograms:write

Requires programs:write and an Idempotency-Key. At least one branch; a branch program answers 409 BRANCH_CARD.

Send an Idempotency-Key header. Safe to retry.

Path

iduuidRequired

Body

branchIdsuuid[]Required

Returns 200

idstringRequired
namestringRequired: The merchant's label; empty means "use the reward".
cardTypestringRequired: stamp, points, cashback, prepaid, tiered, subscription, points_tier
cardColorstringRequired: #rrggbb
rewardNamestringRequired
branchIdsstring[]Required
ownerBranchIdstring or nullRequired
memberCountintegerRequired: Customers holding the program; any blocks deletion.
settingsobject or nullRequired: The rules of a Stamp, Points, Tiered or Points and tiers program; null for other types (not configurable through the API yet).
settings.stampsRequiredinteger: 3 to 20.
settings.maxStampsPerVisitinteger: 1 to 5.
settings.welcomeStampsinteger: 0 to 3.
settings.nextCardBonusboolean
settings.selfStampboolean
settings.uniqueQrboolean
settings.earnRuleobject
settings.earnRule.modeenumRequired: One of per_visit, per_taka.
settings.earnRule.pointsintegerRequired
settings.earnRule.perTakainteger
settings.rewardsobject[]
settings.rewards[].namestringRequired: 2 to 40 characters.
settings.rewards[].costintegerRequired: Each reward needs a different cost.
settings.minorUnitDigitsinteger: Digits after the decimal point of one major unit: 2 for USD (1250 is 12.50), 0 for JPY, 3 for KWD. A program made before currencies existed reads BDT.
suspendedbooleanRequired

Errors

409BRANCH_CARD

Request

curl -X PUT "https://app.revisit.cards/v1/developer/programs/e01b010d-2c65-48e1-83a0-acad79f8d3b4/branches" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-7b1d-4c3e-9a6f-0d4b8e176241" \
  -H "Content-Type: application/json" \
  -d '{
    "branchIds": [
      "b703a365-4444-483c-a078-fa042c813757"
    ]
  }'

Response

{
  "data": {
    "branchIds": [
      "b703a365-4444-483c-a078-fa042c813757"
    ],
    "cardColor": "#1F2937",
    "cardType": "stamp",
    "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
    "memberCount": 12,
    "name": "Dhanmondi",
    "ownerBranchId": "21132f65-97fe-438b-8f09-6910b9e227c0",
    "rewardName": "Free chai",
    "settings": {
      "maxStampsPerVisit": 1,
      "nextCardBonus": false,
      "selfStamp": false,
      "stampsRequired": 3,
      "uniqueQr": false,
      "welcomeStamps": 3
    },
    "suspended": false
  },
  "requestId": "33a792a6-b712-40ab-bf97-7edff560ab1b",
  "success": true
}

Make a branch program a chain-wide program

POST/programs/{id}/promote

Scopeprograms:write

Requires programs:write and an Idempotency-Key. Not available to a branch-limited key. Members and balances stay.

Send an Idempotency-Key header. Safe to retry.

Path

iduuidRequired

Returns 200

idstringRequired
namestringRequired: The merchant's label; empty means "use the reward".
cardTypestringRequired: stamp, points, cashback, prepaid, tiered, subscription, points_tier
cardColorstringRequired: #rrggbb
rewardNamestringRequired
branchIdsstring[]Required
ownerBranchIdstring or nullRequired
memberCountintegerRequired: Customers holding the program; any blocks deletion.
settingsobject or nullRequired: The rules of a Stamp, Points, Tiered or Points and tiers program; null for other types (not configurable through the API yet).
settings.stampsRequiredinteger: 3 to 20.
settings.maxStampsPerVisitinteger: 1 to 5.
settings.welcomeStampsinteger: 0 to 3.
settings.nextCardBonusboolean
settings.selfStampboolean
settings.uniqueQrboolean
settings.earnRuleobject
settings.earnRule.modeenumRequired: One of per_visit, per_taka.
settings.earnRule.pointsintegerRequired
settings.earnRule.perTakainteger
settings.rewardsobject[]
settings.rewards[].namestringRequired: 2 to 40 characters.
settings.rewards[].costintegerRequired: Each reward needs a different cost.
settings.minorUnitDigitsinteger: Digits after the decimal point of one major unit: 2 for USD (1250 is 12.50), 0 for JPY, 3 for KWD. A program made before currencies existed reads BDT.
suspendedbooleanRequired

Request

curl -X POST "https://app.revisit.cards/v1/developer/programs/e01b010d-2c65-48e1-83a0-acad79f8d3b4/promote" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-7b1d-4c3e-9a6f-0d4b8e61f1db"

Response

{
  "data": {
    "branchIds": [
      "b703a365-4444-483c-a078-fa042c813757"
    ],
    "cardColor": "#1F2937",
    "cardType": "stamp",
    "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
    "memberCount": 12,
    "name": "Chai card",
    "ownerBranchId": "21132f65-97fe-438b-8f09-6910b9e227c0",
    "rewardName": "Free chai",
    "settings": {
      "maxStampsPerVisit": 1,
      "nextCardBonus": false,
      "selfStamp": false,
      "stampsRequired": 3,
      "uniqueQr": false,
      "welcomeStamps": 3
    },
    "suspended": false
  },
  "requestId": "7df43283-5b76-4a3c-80f8-37442f824c4f",
  "success": true
}