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-Keyheader oridempotencyKeyfield). 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
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):
| Endpoint | Auth / Guard | Primary Purpose |
|---|---|---|
POST /api/v1/scans/pass/:passId/use | x-scanner-key | Scanner-initiated stamp, point, or balance mutation via request payload. |
POST /api/v1/passes/:id/use | Workspace JWT / API Key | Backend CRM/webhook-initiated stamp or point execution on a pass. |
POST /api/v1/mechanics/redeem | Scanner Key or JWT (request payload) | Executes a full-card stamp or reward redemption (action: 'DECREMENT'). |
GET /api/v1/mechanics/:mechanicId/passes/:passId/state | Scanner Key or JWT | Returns current stamps/points balance plus allowedActions capability flags. |
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger | Scanner Key or JWT | Lists historical mechanic transactions (?limit=50, max 500). |
GET /api/v1/balance-changes | Workspace JWT / API Key | Queries 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:
/api/v1/scans/pass/pass_loy_884120/use
{
"action": "INCREMENT",
"mechanicId": "11111111-2222-4333-8444-555555555555",
"amount": "2",
"deviceId": "ios-idfv-cafe-03",
"operatorId": "barista_03",
"location": "Main Counter"
}
Field (request payload) | Type | Validation / Notes |
|---|---|---|
action | enum (optional, defaults to INCREMENT) | One of 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'. |
mechanicId | UUID (optional) | Verifies the target mechanic bound to this pass. |
amount | decimal string (optional) | Must match /^\d+(\.\d{1,6})?$/ (e.g. "2" or "12.90"). |
deviceId / operatorId / location | strings (optional) | Recorded on the audit ledger for shift reconciliation. |
idempotencyKey | string (optional) | Must match Idempotency-Key header if both are provided. |
Response (200 OK — IPassUseResponse):
{
"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
{
"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):
{
"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
Threshold Evaluation: Checks whether the updated balance crosses into a higher tier (e.g.,
Bronze: 0–249,Silver: 250–499,Gold: 500+). -
2
Visual & Asset Hydration: Replaces tier-specific background colors, strip/banner images, and tier label fields on the pass record.
-
3
Lock-Screen Celebration Alert: Triggers an Apple Wallet
changeMessagenotification (e.g., "Congratulations! You reached Gold Tier") and emits theTIER_CHANGEDworkflow 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.
