Skip to main content
Referral campaigns let customers invite others using a unique referral code. When someone completes a qualifying action that includes that code, Masivo can reward the referrer (who shared the code) and, if configured, the referee (who used it).

​
How referrals work

​
Roles

Self-referral is ignored: the same customer cannot use their own code, and referred_customer_id matching the event customer is rejected.

​
Requesting a code

Referrers obtain a code through the Storefront API: POST /api/storefront/v1/customers/{id}/referrals/request-code If the customer already has a code for that campaign, the existing row is returned. New codes:
  • Are 8 characters from A–Z / 0–9 (ambiguous characters like I and O are omitted)
  • Set max_uses from attributes.max_participations_per_customer
  • Start with uses_count: 0

​
Qualifying event

The referee must emit a behavior event that:
  1. Matches campaign attributes.trigger (for example "PURCHASE" or a custom type such as "REFERRALS")
  2. Includes a valid referral_code
  3. Is processed as fulfilled when you want rewards applied (same fulfillment rules as other campaigns)
On a successful match, Masivo:
  1. Increments the code’s uses_count (blocked when uses_count >= max_uses)
  2. Increments campaign attributes.uses
  3. Applies referee rewards from attributes.referee_rules on the referee’s event (if any rules exist)
  4. Inserts a REWARD_REFERRER event for the referrer and processes it asynchronously with the campaign’s main rules

​
Referrer vs referee rules

At least one of referrer or referee rewards must be configured when creating the campaign. Referrer rules can include normal conditions (payment method, audiences, and so on). Those conditions are evaluated on the REWARD_REFERRER event context. Example shape:

​
Campaign configuration

Hard limit enforced at processing time is the code use limit (uses_count vs max_uses), not stock.

​
Event reversal

Reversing the referee’s original event can also reverse the linked referrer reward:
  1. Masivo looks up a REWARD_REFERRER event whose data.original_event_id matches the reversed event.
  2. If that referrer event is RESOLVED, it is included in the normal reversal flow.
There is no separate public “referral history” endpoint; progress is visible via wallet lines, transactions, and events.

​
Comparison with Punch Cards