Email referral program

Build a referral program where an existing user emails a friend, the friend signs up, and both earn points once the friend makes a first qualifying purchase. Your app sends the emails and owns the referral codes. Scrip records who invited whom, counts each stage, pays both sides, and keeps the accounting.

What you’ll build

Stage	Event your app sends	What Scrip records
Referrer sends an invite	`referral_invited` for the referrer	`invites_sent` counter on the referrer
Friend signs up from the link	`referral_signup` for the friend, with `referrer_id`	`referred_by` attribute and `referred` tag on the friend, `referral_signups` counter on the referrer
Friend makes a first purchase of $25 or more	Ordinary `purchase` for the friend	500 points and the `referral_qualified` tag on the friend, 500 points and the `referrals_paid` counter on the referrer

The result is one rule set with three rules and one monthly budget.

Who does what

Your app	Scrip
Generates the referral code or link and sends the email	Enrolls the referrer on their first invite event
Resolves the code back to the referrer’s `external_id` at signup	Stores the attribution on the friend and counts the signup for the referrer
Sends purchases as ordinary events	Detects the first qualifying purchase and pays both sides once
Reads counters to show “3 invited, 1 joined, 1 earned”	Caps total payout with a budget and records every credit in the ledger

Scrip does not send email or generate codes. Referral links are part of your product.

Assumptions

This example assumes you already have:

A program created, with on_unknown_participant left at CREATE
An asset linked to that program (POINTS, scale 0, UNLIMITED, LOT)

See the quickstart if you need help with setup.

Create the rule set

POST /v1/programs/{{PROGRAM_ID}}/rule-sets

{"key": "referrals", "name": "Referrals"}

Save the returned ID as REFERRALS_RULE_SET_ID. Create the three rules below in the order shown. Scrip numbers them as they are added.

1. Count the invite

When a user sends an invite, your app sends an event for the referrer. The idempotency key is the referral code, so a resent email does not count twice.

{
  "program_id": "{{PROGRAM_ID}}",
  "external_id": "user_123",
  "idempotency_key": "referral-invite-k7f2m9",
  "event_timestamp": "2026-03-01T14:00:00Z",
  "event_data": {
    "type": "referral_invited",
    "referral_code": "k7f2m9"
  }
}

If user_123 is not yet a participant, this event enrolls them.

{
  "program_id": "{{PROGRAM_ID}}",
  "rule_set_id": "{{REFERRALS_RULE_SET_ID}}",
  "name": "count_invite",
  "condition": "event.type == \"referral_invited\"",
  "actions": [
    {"type": "COUNTER", "key": "invites_sent", "value": "1"}
  ]
}

When the friend signs up through the link, your app resolves the code to the referrer and sends an event for the friend. The friend does not need to exist yet; this event enrolls them.

{
  "program_id": "{{PROGRAM_ID}}",
  "external_id": "user_456",
  "idempotency_key": "referral-signup-user_456",
  "event_timestamp": "2026-03-02T09:15:00Z",
  "event_data": {
    "type": "referral_signup",
    "referrer_id": "user_123",
    "referral_code": "k7f2m9"
  }
}

The rule stores the attribution on the friend and counts the signup for the referrer. The referred tag makes a second signup event for the same friend skip, and the external_id check rejects a user who referred themselves.

{
  "program_id": "{{PROGRAM_ID}}",
  "rule_set_id": "{{REFERRALS_RULE_SET_ID}}",
  "name": "record_signup",
  "condition": "event.type == \"referral_signup\" && has(event.referrer_id) && event.referrer_id != participant.external_id && !(\"referred\" in participant.tags)",
  "actions": [
    {"type": "SET_ATTRIBUTE", "key": "referred_by", "value": "${{ event.referrer_id }}"},
    {"type": "TAG", "tag": "referred"},
    {
      "type": "COUNTER",
      "key": "referral_signups",
      "value": "1",
      "target": {"external_id": "${{ event.referrer_id }}"}
    }
  ]
}

Nothing is paid at signup. Paying on the first qualifying purchase keeps throwaway signups from earning anything.

3. Qualify on the first purchase

Purchases arrive as ordinary events, with nothing referral-specific in them:

{
  "program_id": "{{PROGRAM_ID}}",
  "external_id": "user_456",
  "idempotency_key": "order-88213-completed",
  "event_timestamp": "2026-03-05T18:40:00Z",
  "event_data": {
    "type": "purchase",
    "amount": 42.50,
    "order_id": "88213"
  }
}

The rule fires once per referred friend. It pays the friend 500 points and marks them qualified. It also pays the referrer 500 points and adds one to their referrals_paid count, finding them through the referred_by attribute saved at signup. The budget caps referral payouts for both sides together at 500,000 points a month.

{
  "program_id": "{{PROGRAM_ID}}",
  "rule_set_id": "{{REFERRALS_RULE_SET_ID}}",
  "name": "qualify_referral",
  "condition": "event.type == \"purchase\" && event.amount >= 25 && \"referred\" in participant.tags && !(\"referral_qualified\" in participant.tags)",
  "actions": [
    {"type": "TAG", "tag": "referral_qualified"},
    {
      "type": "CREDIT",
      "asset_id": "{{ASSET_ID}}",
      "amount": "500",
      "description": "Referral welcome bonus"
    },
    {
      "type": "CREDIT",
      "asset_id": "{{ASSET_ID}}",
      "amount": "500",
      "target": {"external_id": "${{ participant.attribute.referred_by }}"},
      "description": "Referral bonus"
    },
    {
      "type": "COUNTER",
      "key": "referrals_paid",
      "value": "1",
      "target": {"external_id": "${{ participant.attribute.referred_by }}"}
    }
  ],
  "budgets": [
    {
      "asset_id": "{{ASSET_ID}}",
      "limit": "500000",
      "schedule_type": "CRON",
      "cron_expression": "0 0 1 * *"
    }
  ]
}

The target reads referred_by from the friend. The condition requires the referred tag, and record_signup always sets that tag and the attribute together, so the attribute is there whenever this rule fires. Without that check, a friend with no referred_by would fail the whole purchase event. See Dynamic targets. When the monthly budget runs out, the rule still matches but none of its actions run, and Scrip records the skip with reason BUDGET_EXCEEDED. Neither side is paid and the friend is not marked qualified, so their next qualifying purchase after the budget resets pays both sides.

Show progress to the referrer

Your app reads the referrer’s counters to render a referral page:

GET /v1/participants/{id}/state/counters

{
  "invites_sent": 3,
  "referral_signups": 1,
  "referrals_paid": 1
}

To notify the referrer when they are paid, subscribe a webhook endpoint to balance.credited. The payload carries the description from the rule, so your handler can tell a referral bonus from other credits.

Edge cases and watchouts

Self-referral

record_signup requires event.referrer_id != participant.external_id, so a user who signs up with their own code is not marked as referred and never qualifies. Reject the code in your app as well so the user sees an error instead of a silent no-op.

The referrer is not in the program

Actions that target the referrer need the referrer to be enrolled and not closed. Otherwise the whole event fails. The referrer’s referral_invited event enrolls them, so record_signup fails only if your app skips step 1 or the referrer’s account is closed. If the referrer is closed before the friend’s first purchase, the purchase event fails and the friend is not paid either. Check the referrer’s status before sending the signup event.

Limits per referrer

qualify_referral runs on the friend’s purchase event, so its condition sees the friend’s data, not the referrer’s counters. The simplest limit lives in your app: read invites_sent or referrals_paid before issuing a new code. To enforce the limit in Scrip, send the referrer’s payout as a separate event addressed to the referrer. In qualify_referral, replace the referrer’s CREDIT and COUNTER with this SCHEDULE_EVENT:

{
  "type": "SCHEDULE_EVENT",
  "delay": "1s",
  "event_data": {"type": "referral_payout", "friend_id": "${{ participant.external_id }}"},
  "target": {"external_id": "${{ participant.attribute.referred_by }}"}
}

One second later, Scrip delivers a referral_payout event to the referrer. A fourth rule runs on that event, so its condition can read the referrer’s own referrals_paid count. This one pays each referrer for at most 10 referrals:

{
  "program_id": "{{PROGRAM_ID}}",
  "rule_set_id": "{{REFERRALS_RULE_SET_ID}}",
  "name": "pay_referrer",
  "condition": "event.type == \"referral_payout\" && participant.counter.referrals_paid < 10.0",
  "actions": [
    {"type": "CREDIT", "asset_id": "{{ASSET_ID}}", "amount": "500", "description": "Referral bonus"},
    {"type": "COUNTER", "key": "referrals_paid", "value": "1"}
  ]
}

Decide where the budget lives. On qualify_referral it now counts only the friend’s bonus, and running out also stops the referrer’s payout from being scheduled. On pay_referrer it caps referrer payouts only. With this setup the referrer is paid by a separate event, so a refund means reversing two events: the friend’s purchase and the referrer’s referral_payout.

The friend never buys

Nothing is paid and nothing needs cleaning up. The referred tag and referred_by attribute stay on the friend so a later purchase can still qualify. To add a deadline, add duration_days(now - participant.enrolled_at) <= 30.0 to the qualify_referral condition.

The qualifying purchase is refunded

The purchase event paid both sides, so reversing it takes back the friend’s 500 points and the referrer’s 500 points. Reversal takes points back from the lots (individually tracked credits) each award created, which is why the setup above uses a LOT-mode asset:

POST /v1/events/{id}/reverse

Reversal does not undo tags or counters. The referral_qualified tag stays on the friend, so a later purchase does not pay either side again. The referrer’s referrals_paid count also stays as it is. The reversal response lists both changes, so you can send a compensating event if your policy requires it. See Reversing an event.

Replayed events

Every event in this flow uses an idempotency key built from a stable ID, such as the referral code or the order ID. A resent referral_signup returns the original event without reprocessing, and the tags on the friend make record_signup and qualify_referral skip on any event that does reach the rules twice.

Next steps

Targeting

Credit a participant other than the one who sent the event.

Campaigns

Double the referral bonus for a month without touching these rules.

Webhooks

Tell the referrer when they have been paid.

Recipes

Integrations

Email referral program

What you’ll build

Who does what

Assumptions

Create the rule set

1. Count the invite

3. Qualify on the first purchase

Show progress to the referrer

Edge cases and watchouts

Self-referral

The referrer is not in the program

Limits per referrer

The friend never buys

The qualifying purchase is refunded

Replayed events

Next steps

Targeting

Campaigns

Webhooks

​What you’ll build

​Who does what

​Assumptions

​Create the rule set

​1. Count the invite

​2. Record the signup

​3. Qualify on the first purchase

​Show progress to the referrer

​Edge cases and watchouts

​Self-referral

​The referrer is not in the program

​Limits per referrer

​The friend never buys

​The qualifying purchase is refunded

​Replayed events

​Next steps

Targeting

Campaigns

Webhooks

What you’ll build

Who does what

Assumptions

Create the rule set

1. Count the invite

2. Record the signup

3. Qualify on the first purchase

Show progress to the referrer

Edge cases and watchouts

Self-referral

The referrer is not in the program

Limits per referrer

The friend never buys

The qualifying purchase is refunded

Replayed events

Next steps