Skip to main content
Punch Cards are a campaign type that tracks progress toward a fixed number of punches. Each qualifying event can add one punch to the customer’s active card. Effects attached to a specific punch number are granted when that punch is reached.

​
How punch cards work

A punch card campaign combines three ideas: cards (progress records), punches (steps on a card), and per-punch rewards (effects labeled by punch number).

​
Cards and punches

Each customer can have an active punch card per campaign. On the first qualifying event (when they are allowed to participate), Masivo creates a card with:
  • punches: 0
  • max_punches: from campaign attributes.punches_per_card (default 10 if missing when the card is created)
  • status: ACTIVE
Only fulfilled events increment punches. Unfulfilled events can still match the campaign and preview effects, but they do not change the card. When punches reaches max_punches, the card becomes FINISHED and punches are capped at max_punches (they do not go past the limit).

​
How many cards a customer can have

Participation is controlled by campaign attributes: If there is already an ACTIVE card, the customer continues on that card. A new card is created only when there is no active card and the customer is still under the card limit (or unlimited cards is enabled).

​
Per-punch rewards

Rewards are not granted on every punch by default. Effects are selected when their label matches the current punch number as a string ("1", "2", …). Optional tier_id on an effect restricts it to that tier; effects without tier_id apply to all tiers. Example: a 5-punch card that rewards on punch 3 and punch 5:
Campaign rules still go through the normal rules engine for matching (event type / conditions). The punch processor then filters effects by punch label and tier.

​
Punch card lifecycle

There is no loss window or scheduled reset. Completed cards stay FINISHED until a new card is created under the participation rules above.

​
Campaign configuration

Punch card processing requires punch-card campaign consent. If consent.purposes.punchcard_campaigns is explicitly false, matching campaigns are skipped. Missing consent is treated as allowed.

​
Storefront API

List a customer’s cards: GET /api/storefront/v1/customers/{id}/punch-cards Progress is driven by Emit event: send the campaign trigger event with fulfilled: true for the customer.

​
Comparison with Score Streaks