Skip to content
Help Center Guide · Redemption & TransactionsOnboarding Phase 2
3 min readVerified 2026-11-16

Loyalty Points & Stamps

Execute stamp punch awards, full-card reward resets, points-per-visit rules, and automatic tier threshold evaluations.

In This Guide

Interactive UI Walkthroughs

Open in 6-Phase Onboarding Guide

Inspect exact dashboard panels, controls, and zoomed callouts related to this guide.

Zoomed UI focus
Key UI elements

Add a Pass Mechanic selector (Zoomed)

Choose from 6 built-in mechanics: Stamp Pass, Stamp Redemption, Stored Value, Points & Tiers, Once-per-day validation, or Extend Expiry.

Overview

Passinstance processes stamp card punches, loyalty point accruals, automatic tier promotions, and reward redemptions through Loyalty & Stamp Engine, Pass Mechanics API, and Tier Progression Engine. Staff and backend integrations can trigger loyalty updates via a standard counter scan (POST /api/v1/scans), direct scanner pass execution (POST /api/v1/scans/pass/:passId/use), workspace-authenticated pass usage (POST /api/v1/passes/:id/use), POS terminal redemption (POST /v1/pos/redeem), or explicit reward redemption (POST /api/v1/mechanics/redeem).

Important: All loyalty balance mutations and reward redemptions execute in atomic transactions with strict idempotency enforcement (Idempotency-Key header or idempotencyKey field). After any stamp, point, or tier change, Passinstance automatically regenerates dynamic strip imagery and dispatches silent push updates to Apple Wallet and Google Wallet.

Architecture & Mechanic Execution Flow

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
LOYALTY ACCRUAL, TIER UPGRADE & REWARD REDEMPTION
PARTICIPATING SYSTEM ACTORS
P1 Scanner / POS Terminal
P2 Loyalty & Stamp Engine / Mechanics
P3 Tier Progression Engine & Wallet Push
STEP 1 REQUEST / ACTION POST/api/v1/scans
STEP 2 REQUEST / ACTION Execute ScanAction / Mechanic:
›
{ action: "INCREMENT" }
›
INCREMENT / DECREMENT
›
CREDIT / DEBIT / SET
›
STAMP_CARD / LOYALTY_PROGRAM
STEP 3 REQUEST / ACTION Check Tier Thresholds
STEP 4 REQUEST / ACTION Hydrate Tier Assets & Colors
STEP 5 RESPONSE Persist Balance & Ledger
STEP 6 RESPONSE 200 OK (resultingValue)
STEP 7 REQUEST / ACTION Emit POINTS_UPDATED /
›
8. APNs & Google Wallet Push
›
TIER_CHANGED events
›
(Updated Strip & Tier Badge)

Allowed Mechanic Actions & State Endpoints

request payload accepts one of seven explicit actions (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET), matching the scan action ledger taxonomy (INCREMENT | DECREMENT | VALIDATE | DEBIT | CREDIT | NOOP):

EndpointAuth / GuardPrimary Purpose
POST /api/v1/scans/pass/:passId/usex-scanner-keyScanner-initiated stamp, point, or balance mutation via request payload.
POST /api/v1/passes/:id/useWorkspace JWT / API KeyBackend CRM/webhook-initiated stamp or point execution on a pass.
POST /api/v1/mechanics/redeemScanner Key or JWT (request payload)Executes a full-card stamp or reward redemption (action: 'DECREMENT').
GET /api/v1/mechanics/:mechanicId/passes/:passId/stateScanner Key or JWTReturns current stamps/points balance plus allowedActions capability flags.
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledgerScanner Key or JWTLists historical mechanic transactions (?limit=50, max 500).
GET /api/v1/balance-changesWorkspace JWT / API KeyQueries tenant-wide loyalty and prepaid balance mutation history.

Endpoints for Loyalty Accrual & Reward Redemption

1. Direct Mechanic Execution (POST /api/v1/scans/pass/:passId/use)

When a scanner or POS terminal has looked up the pass (GET /api/v1/scans/pass?barcode=...), it can execute a stamp addition, point award, or decrement directly against the UUID :passId using request payload:

POST /api/v1/scans/pass/pass_loy_884120/use
Headers
x-scanner-key sk_live_cafe_counter_01
Idempotency-Key 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Content-Type application/json
JSON
{
  "action": "INCREMENT",
  "mechanicId": "11111111-2222-4333-8444-555555555555",
  "amount": "2",
  "deviceId": "ios-idfv-cafe-03",
  "operatorId": "barista_03",
  "location": "Main Counter"
}
Field (request payload)TypeValidation / Notes
actionenum (optional, defaults to INCREMENT)One of 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'.
mechanicIdUUID (optional)Verifies the target mechanic bound to this pass.
amountdecimal string (optional)Must match /^\d+(\.\d{1,6})?$/ (e.g. "2" or "12.90").
deviceId / operatorId / locationstrings (optional)Recorded on the audit ledger for shift reconciliation.
idempotencyKeystring (optional)Must match Idempotency-Key header if both are provided.

Response (200 OK — IPassUseResponse):

JSON
{
  "success": true,
  "data": {
    "scanId": "scan_01hxyz8820ab",
    "passId": "pass_loy_884120",
    "action": "INCREMENT",
    "success": true,
    "resultingValue": "8"
  },
  "description": "Pass INCREMENT successfully",
  "errors": [],
  "statusCode": 200
}

2. Redeeming an Unlocked Reward (POST /api/v1/mechanics/redeem)

When a customer claims an earned stamp card reward or spends accrued units, invoke POST /api/v1/mechanics/redeem with request payload:

POST /api/v1/mechanics/redeem Headers: x-scanner-key: sk_live_cafe_counter_01 (or Authorization: Bearer <jwt>) Idempotency-Key: 4f8b92c1-7a1e-4b33-9c12-4b1c30a9d872 Content-Type: application/json

JSON
{
  "passId": "a1b2c3d4-e5f6-4a7b-8c9d-0123456789ab",
  "mechanicId": "11111111-2222-4333-8444-555555555555",
  "ruleId": "default",
  "idempotencyKey": "4f8b92c1-7a1e-4b33-9c12-4b1c30a9d872"
}

(Note: Both passId and mechanicId — and optional idempotencyKey inside the JSON body — must be valid UUIDs; if supplied, ruleId must equal "default".)

Response (200 OK — IRedeemResponse):

JSON
{
  "success": true,
  "newBalance": 0,
  "newBalanceDecimal": "0",
  "reward": "default",
  "message": "Reward redeemed successfully"
}

Automatic Tier Upgrades (Tier Progression Engine)

Whenever a scan, POST /api/v1/scans/pass/:passId/use, or POST /v1/pos/redeem (operation: "ADD_POINTS" or "ADD_STAMPS") mutates a pass's point or visit balance, Tier Progression Engine evaluates the template's configured tier thresholds:

  1. 1
    Threshold Evaluation: Checks whether the updated balance crosses into a higher tier (e.g., Bronze: 0–249, Silver: 250–499, Gold: 500+).
  2. 2
    Visual & Asset Hydration: Replaces tier-specific background colors, strip/banner images, and tier label fields on the pass record.
  3. 3
    Lock-Screen Celebration Alert: Triggers an Apple Wallet changeMessage notification (e.g., "Congratulations! You reached Gold Tier") and emits the TIER_CHANGED workflow trigger so you can automate bonus welcome perks.

Learn more about configuring loyalty programs in Loyalty & Stamp Cards and automating tier rewards in Workflow Configuration.

Related Product & Developer Documentation

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.