Overview
Unlike fixed-threshold stamp cards, Rewards & Loyalty Programs model continuous points accumulation and multi-tier progression (e.g. Bronze -> Silver -> Gold -> Platinum). Passinstance provides an enterprise loyalty engine featuring dynamic point-to-spend accrual rules, automatic tier evaluation, reward redemption APIs, and real-time wallet push updates.
Backend Architecture & Loyalty Engine
Loyalty programs combine continuous balance tracking with structured tier definitions in the Passinstance data model:
-
Pass Type (pass type):
storeCard(displays active points balance in prominent primary zones). -
Catalog Demo Blueprint:
retail-loyalty. -
Mechanic Type (mechanic type):
LOYALTY_PROGRAM. -
Core Loyalty Models:
- Tier: Configures threshold requirements (e.g. 500 points for Silver, 1,500 points for Gold), tier perks, custom visual colors, and dedicated tier badge images. - BalanceChange: Immutable transaction ledger recording every points accrual, redemption deduction, and administrative adjustment.
Points Accrual & Tier Progression Engine
The Pass Mechanics Engine and Tier Progression Engine execute the loyalty rules:
1. Accrual Calculation
When a purchase or visit occurs:
-
Points step defaults to
defaultChangeValue(canonical), falling back toconfig.pointsPerScanor1. -
For POS and e-commerce integrations, points are calculated dynamically based on purchase amount:
earnedPoints = floor(purchaseTotal * pointsMultiplier)
newBalance = clamp(currentBalance + earnedPoints, minimumValue, maximumValue)
-
If
autoResetAtMaximum: trueorconfig.onCap === "reset", the points balance resets toresetTargetValue(or initial balance) upon reachingmaximumValue.
2. Automated Tier Upgrades (Tier Progression Engine)
After every balance mutation, the Tier Progression Engine evaluates the member's cumulative points against active tier thresholds:
-
If a boundary is crossed, the service promotes the member to the higher tier.
-
It automatically updates the visual card styling (changing background colors, header labels, and tier badge icons).
-
It triggers a silent APNs push and Google Wallet REST update, alerting the customer with a native lock-screen notification: "Congratulations! You have reached Gold Tier."
Reward Redemption API
When a customer redeems points for discounts, free items, or merchandise in store or online:
HTTP Request
/api/v1/mechanics/redeem
{
"passId": "8f94d930-b302-4fc8-9f12-000000000001",
"mechanicId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
"idempotencyKey": "redeem_tx_88194"
}
HTTP Response (200 OK)
{
"success": true,
"newBalance": 240,
"newBalanceDecimal": "240",
"message": "Reward redeemed successfully"
}
E-Commerce & Multi-Channel Synchronization
Connect in-store checkout counters and online web stores to maintain a unified customer ledger (transaction type: EARN, REDEEM, ADJUST, REFUND, TRANSFER, BONUS, PENALTY, SCAN, API, ADJUSTMENT):
-
Shopware 6 / Shopify Connectors: Ingest online order webhooks (
/api/v1/automations/webhooks/shopify/:customerId,/api/v1/automations/webhooks/woocommerce/:customerId, or Shopware plugin webhooks) and credit customer wallet passes matched byexternalIdautomatically. -
Canonical Pass Use API (
POST /api/v1/passes/:id/use): Preferred programmatic balance/points mutation endpoint for ERPs, apps, and backend services (with scanner-key counterpartPOST /api/v1/scans/pass/:passId/use). Legacy mechanic event ingestion (POST /api/v1/mechanics/:mechanicId/events) remains supported for backward compatibility, though deprecated for new integrations.
Important: Configure
changeMessage: "Points balance updated to %@"on your primary points field in the template editor. Whenever points are earned or deducted, the customer's lock screen immediately surfaces the updated balance.
Learn more about our Loyalty Solution, explore Loyalty Cards, or review the Loyalty Progression Rules Guide.
