Loyalty — Stamps

stemp supports digital stamp cards that work like physical punch cards — each interaction adds a stamp, and users earn a reward when the card is full. Stamps are managed per wallet pass and configured per template.

Required scope: loyalty:manage for all write operations, pass:read for reading state and history.

Get Stamp State

curl https://api.stemp.app/api/v1/walletpasses/{walletPassId}/stamps \
  -H "Authorization: Bearer <token>"

Response:

{
  "id": "ss_abc123",
  "walletPassId": "wp_abc456",
  "currentStamps": 5,
  "maxStampsSnapshot": 10,
  "totalStampsCollected": 15,
  "timesCompleted": 1,
  "lastStampAt": "2026-01-15T14:00:00Z"
}

Field	Description
`currentStamps`	Current stamps on the active card
`maxStampsSnapshot`	Stamps required to complete the card
`totalStampsCollected`	All-time stamps across all completions
`timesCompleted`	How many times the card has been fully completed
`lastStampAt`	Timestamp of the most recent stamp

Add a Stamp

curl -X POST https://api.stemp.app/api/v1/walletpasses/{walletPassId}/stamps/add \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Purchase at Main St. location"
  }'

The note field is optional (max 512 characters) and is stored in the stamp history.

Remove a Stamp

curl -X POST https://api.stemp.app/api/v1/walletpasses/{walletPassId}/stamps/remove \
  -H "Authorization: Bearer <token>"

Set Stamp Count

Set the stamp count to an exact value (0–10):

curl -X POST https://api.stemp.app/api/v1/walletpasses/{walletPassId}/stamps/set \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "stamps": 7
  }'

Reset Stamps

Reset the stamp count to zero:

curl -X POST https://api.stemp.app/api/v1/walletpasses/{walletPassId}/stamps/reset \
  -H "Authorization: Bearer <token>"

Stamp History

curl "https://api.stemp.app/api/v1/walletpasses/{walletPassId}/stamps/history?page=0&size=20" \
  -H "Authorization: Bearer <token>"

Each history entry includes:

{
  "id": "sh_abc123",
  "walletPassId": "wp_abc456",
  "stampsBefore": 4,
  "stampsAfter": 5,
  "stampsDelta": 1,
  "actionType": "ADD",
  "triggeredByMemberId": "mem_xyz789",
  "note": "Purchase at Main St. location",
  "createdAt": "2026-01-15T14:00:00Z"
}

Stamp Card Completion

When a user collects all stamps (currentStamps reaches maxStampsSnapshot):

A stamp.reward_triggered webhook event fires.
A stamp.card_completed webhook event fires.
The card resets automatically (depending on template configuration).
timesCompleted increments by 1.

POS Integration Pattern

Customer presents their wallet pass QR code.
Scan the QR code to get the walletPassId.
Call POST /stamps/add to add a stamp.
Listen for stamp.reward_triggered webhook to fulfill rewards.

Loyalty (Stamps)