#Stamp cards

A stamp card is the punch card in a customer's wallet: ten coffees, then the eleventh is free. It rewards a habit rather than a balance, which makes it the right tool for the thing you want somebody to do repeatedly, and a good complement to points rather than a replacement for them.

Stamp cards live in the Stamp cards section of the Overview page. Add stamp card creates a card type; Stamp cards in the sidebar lists the individual cards your members are filling. See Setting up loyalty for the program around them.

#Types and cards

There are two things with similar names, and the difference matters.

• A stamp card type is your design: what it is called, how stamps are earned, and how big it is. Ridgeline has one, called Coffee club.
• A stamp card is one customer's copy of it, holding their stamps.

Stamps live on the card, and customers cycle through cards. A member does not have a running stamp total; they have a card with some stamps on it, and when it fills, it closes and the next one starts. That is why a completed card stays in the list: it is the record of a reward that was earned, not a counter that was reset.

Cards are created when they are needed. A member's first stamp opens their first card, so there is nothing to hand out in advance and nobody is holding an empty card they never started.

By default a member has one open card of a type at a time, and every new stamp lands on it. Turn on Allow several open cards at once if you would rather they could run more than one, in which case stamps go to the oldest open card first.

#How stamps are earned

How stamps are earned has three options.

Per amount spent measures against the order subtotal by default, excluding shipping and tax, and can be switched to the order total.

Custom is for the stamps Cascade cannot see: a visit to your physical shop, a class attended, a subscription renewal handled somewhere else. Those go through the stamps API, and once they land they behave exactly like an order-driven stamp.

Ridgeline's Coffee club is Per order, one stamp each.

#How big a card is

A card type has no size field. The size comes from your rules: a card is full when it reaches the highest live "Fills a stamp card" rule that targets it.

That sounds indirect and is deliberate, because it means the reward and the threshold are one thing rather than two that can disagree. To make Ridgeline's card ten long, add a rule in the Stamp cards section with the trigger Fills a stamp card, Stamps needed set to 10, and the reward you want. The card type's summary immediately reads "Cards of this type complete at 10 stamps."

A few consequences worth knowing:

• A type with no rule targeting it never completes. Cards keep collecting stamps open-endedly, and the dialog says so. That is a program that is half built rather than a broken one.
• You can reward progress as well as completion. Two rules on the same type, one at 5 stamps and one at 10, give the member something at halfway and something at the end. The card is ten long, because ten is the highest.
• Each rule fires at most once per card. A member cannot collect the same halfway reward twice on one card, and filling their next card earns it again.
• Only rules that are live count. A rule outside its availability window is not part of the card's size, so retiring a rule shrinks the card rather than leaving a threshold nothing pays out at.

#When a card fills

Completion happens after the rules have fired, so the reward and the completion are one event from the member's point of view.

Extra stamps past the last one decides what happens to overflow:

• Carry them to the next card starts their next card with the extras. This is the right default for a habit you want to be continuous.
• Discard them drops the extras.

A single large award can fill more than one card when overflow carries, and each completion issues its own reward.

#Availability

Available from and Available until open and close collecting. Leave them empty and the card stays open indefinitely. This is how you run a seasonal card: a summer card that stops taking stamps in September, with the cards members already filled left untouched.

The window closes the type to every source of stamps: orders stop stamping it, and POST /loyalty-stamps answers 409 rather than stamping a card nobody can still collect on. Adjusting a card by hand from the dashboard still works, so you can correct a mistake after collecting has ended.

#In the dashboard

Stamp cards in the sidebar is a list of members' cards, with the card type, the customer, the stamp count, how many rewards it has produced and whether it is complete. Open one to see its rewards.

You can add or remove stamps by hand from a card, with a reason that is stored on the activity entry. A correction that removes stamps is only a correction: it never fires a rule, never completes a card, and cannot take a card below zero.

#Stamping a card from your own systems

Set the card type's earning to Custom (through the API) and stamp it with POST /loyalty-stamps. This is an admin endpoint, so it takes your secret API key.

curl -X POST https://api.cascade.example.com/loyalty-stamps \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "stampCardTypeId": "019fbc99-35d4-79ac-a14f-fa44ef3d7330",
      "customerEmail": "[email protected]",
      "count": 1,
      "idempotencyKey": "visit-88213"
    }
  }'

{
  "data": {
    "id": "019fbc96-ced9-7159-a5f6-e470280be1b4",
    "stampCardTypeId": "019fbc99-35d4-79ac-a14f-fa44ef3d7330",
    "loyaltyMembershipId": "019fbc6e-0cb7-7aec-be63-210938c62b78",
    "stampCount": 1,
    "completedAt": null,
    "createdAt": "2026-08-01T09:10:27.781Z",
    "updatedAt": "2026-08-01T09:10:27.781Z"
  },
  "awarded": true,
  "loyaltyMembershipId": "019fbc6e-0cb7-7aec-be63-210938c62b78",
  "completedStampCardIds": []
}

The card comes back in the state the award left it, so you can show a customer their progress without a second call. completedStampCardIds names any card the award filled, oldest first, which is how you know to congratulate somebody.

idempotencyKey is your own identifier for the thing that caused the stamp, such as the id of the visit record. Send it again and the same card comes back with awarded set to false and nothing stamped twice. Leave it out and every call counts separately.

#What can go wrong

Two of those are worth planning for.

Unknown customers are refused, not created. A backend integration with a typo in it would otherwise fill your customer list with addresses nobody can reach. Send "createCustomer": true when you would rather have the customer created.

Membership is required. If your program's joining setting is "Customers join the program themselves", a customer who has not joined gets a 409 telling you to enroll them first. On "Enroll customers on their first rewarded activity" they are enrolled by the stamp.

#Webhooks

Stamping fires stampCard.updated, plus stampCard.completed when the award fills the card and stampCard.created when it opens a new one. Every path fires the same events, so a stamp from your own systems and a stamp from an order are indistinguishable to a consumer.

#Migrating stamp balances

Stamp card balances are not part of the member import. A member arriving from another platform starts with a fresh card. See Moving a program to Cascade for how to handle that.