Skip to content
Help Center Guide
3 min readVerified 2026-11-16

Rewards & Loyalty Programs

Design multi-tier Points & Tiers programs with spend-to-points accrual rules, tier upgrades, and loyalty notifications.

In This Guide

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.

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
POINTS ACCRUAL & TIER UPGRADE
PARTICIPATING SYSTEM ACTORS
P1 POS / E-Commerce Purchase
P2 Passinstance Core API
P3 Tier Progression Engine
P4 Customer Wallet Pass
STEP CTX CONTEXT Purchase: €120120 Pts
STEP 1 REQUEST / ACTION POST/api/v1/passes/:id/use
STEP 2 REQUEST / ACTION Update Balance
›
{ action: "INCREMENT", value }
›
(cur + step clamped)
STEP 3 REQUEST / ACTION Evaluate Tiers
›
(Threshold Crossed:
›
SilverGold)
STEP 4 RESPONSE Tier Upgraded
STEP 5 REQUEST / ACTION Silent APNs Push
STEP 6 RESPONSE 200 OK (New Tier)
›
& Google REST PATCH | (Card flips to Gold
›
Lock-screen banner:
›
"Upgraded to Gold!")

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 to config.pointsPerScan or 1.
  • For POS and e-commerce integrations, points are calculated dynamically based on purchase amount:
TEXT
earnedPoints = floor(purchaseTotal * pointsMultiplier)
  newBalance = clamp(currentBalance + earnedPoints, minimumValue, maximumValue)
  • If autoResetAtMaximum: true or config.onCap === "reset", the points balance resets to resetTargetValue (or initial balance) upon reaching maximumValue.

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

POST /api/v1/mechanics/redeem
Headers
X-API-Key <API_KEY>
Content-Type application/json
JSON
{
  "passId": "8f94d930-b302-4fc8-9f12-000000000001",
  "mechanicId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
  "idempotencyKey": "redeem_tx_88194"
}

HTTP Response (200 OK)

JSON
{
  "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 by externalId automatically.
  • 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 counterpart POST /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.

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.