Skip to main content
A stamp card shows a row of stamps that fill in as the holder collects them, such as ten coffees toward a free one. TapAce draws the stamps for each pass and updates them in the holder’s wallet whenever the count changes.

​
Set up the card

Create a template from the Stamp Card starter in the dashboard, then change it in the designer. A stamp card template has the type stamp_card. In the designer you choose:
  • How many stamps the card has, up to 10, and how many sit in a row.
  • The stamp: a built-in icon or your own image, and how empty slots look.
  • The colour or image behind the stamps.
  • The text of the notification sent when stamps change, and optionally a different one for when the card fills.
  • For Google Wallet, the fields shown as Member ID (a required per-pass field) and Member name.
Apple Wallet shows the stamps as a strip across the pass. Google Wallet shows them along the bottom of the card, with the count as the card’s balance, such as 7 / 10. A field can also show the count on the pass itself.

​
Issue a card

Issue it like any pass with POST /v1/passes. It starts with no stamps, or send stamps to start with some:
The pass’s stamps holds the count and the card’s total: { "count": 1, "total": 10 }.

​
Add a stamp

When the holder earns a stamp, call Add stamps:
  • TapAce counts from the pass’s current stamps, so two stamps added at the same time both count.
  • A negative add removes stamps, for example to undo a mistake.
  • The count stays between 0 and the card’s total. A full card stays full until you lower the count; TapAce doesn’t track rewards, so reset the card when the holder redeems one.
To set an exact count, such as 0 after a reward is redeemed, send stamps to Update a pass:

​
Notify the holder

Stamp changes are silent unless you send "notificationMode": "notify". The notification uses the text set on the template, with the count filled in, such as “7 / 10 stamps, closer to a free coffee”. On Apple Wallet it appears on the lock screen; on a card without a field showing the count, it replaces the pass’s Message for you.

​
When the card fills

The template can also set a card-full notification, such as “Congratulations! Your card is full. Show it to collect your free coffee.” It’s sent instead of the usual text when a notifying change takes the count to the card’s total, whether through Add stamps or by setting stamps.
  • On Apple Wallet it replaces the pass’s Message for you, and the holder gets just this one alert.
  • On Google Wallet it has its own title and message.
  • A silent change that fills the card stays silent.
  • If the template has no card-full text, the usual one is sent.
Google Wallet allows 3 notifications per pass in 24 hours. Beyond that, the pass still updates but no alert is shown.

​
Change the design

If you change the number of stamps and deploy the template, passes with more stamps than the new total are lowered to it. The change shows in each pass’s update history.

​
Use the Node.js SDK

Call tapace.passes.addStamps(passId, { add: 2, notificationMode: "silent" }, options) to credit two stamps. The response contains the updated pass and an optional wallet update record. Silent updates have no alert banner. Supply a stable idempotency key derived from the saved sale or award ID, and reuse the same body for retries. A new purchase needs a new operation ID. See the SDK loyalty example.