Referrals API

The official Referrals plugin has an API. Use it to show a subscriber their referral link on your own site, or to send rewards from your shop system. For the plugin itself, see Referrals.

Before you start

Install the Referrals plugin and turn it on in the channel.
Open the API tokens page and make a token for that channel.
Give the token the permissions below.
Write broadcast.referrals/* in the token’s Plugin endpoints field.

Endpoint	Method	Token permission
`program`	GET	Subscribers read
`stats`	GET	Subscribers read
`subscriber`	GET	Subscribers read
`fulfillment`	GET	Subscribers read
`fulfill`	POST	Subscribers write

All addresses start with https://your-broadcast-server/api/plugins/broadcast.referrals/. Send the token in the Authorization header. The data belongs to the channel of the token.

The program

cURL

curl https://your-broadcast-server/api/plugins/broadcast.referrals/program \
  -H "Authorization: Bearer YOUR_TOKEN"

The answer has the configuration and the rewards:

JSON

{
  "enabled": true,
  "description": "Score a discount",
  "template": "upcoming_and_program",
  "rewards": [
    {
      "id": "1",
      "name": "Sticker pack",
      "type": "physical",
      "referrals_needed": 2,
      "description": "",
      "disclaimer": "",
      "image_url": "",
      "tag": "referral-sticker",
      "auto_fulfill": false,
      "template_id": null,
      "email_after_review": false
    },
    {
      "id": "2",
      "name": "10% off",
      "type": "promo_code",
      "referrals_needed": 5,
      "description": "A discount code.",
      "disclaimer": "",
      "image_url": "",
      "tag": "",
      "auto_fulfill": true,
      "template_id": 279,
      "email_after_review": true,
      "promo_codes_total": 2,
      "promo_codes_left": 1
    }
  ]
}

Field	Meaning
`enabled`	`false` when the program is off. Each merge tag of the plugin is then empty
`template`	The template of the email block: `default`, `upcoming_milestone`, `reward_program` or `upcoming_and_program`
`type`	`physical`, `digital` or `promo_code`
`referrals_needed`	The milestone of the reward
`template_id`	The email template of the milestone email, or `null`
`promo_codes_total`, `promo_codes_left`	Only on a `promo_code` reward: the size of the pool and the codes that are not given yet

The numbers

cURL

curl https://your-broadcast-server/api/plugins/broadcast.referrals/stats \
  -H "Authorization: Bearer YOUR_TOKEN"

JSON

{
  "subscribers_with_referrals": 8,
  "total_referred": 21,
  "referrals_per_subscriber": 2.63,
  "pending_referrals": 2
}

A pending referral is a person who signed up through a link and is not confirmed.

One subscriber

Give id or email.

cURL

curl "https://your-broadcast-server/api/plugins/broadcast.referrals/subscriber?email=ada@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"

JSON

{
  "subscriber_id": 3141695,
  "email": "ada@example.com",
  "referral_code": "r1vc5b",
  "referral_link": "https://example.com/join?ref=r1vc5b",
  "referrals": 5,
  "pending_referrals": 0,
  "referred": [
    { "id": 3141781, "email": "ben@example.com", "status": "counted", "at": "2026-11-12T02:31:44.046Z" }
  ],
  "rewards": [
    {
      "key": "earned:8205549236885:3141695:2",
      "subscriber_id": 3141695,
      "email": "ada@example.com",
      "reward_id": "2",
      "reward_name": "10% off",
      "required": 5,
      "status": "fulfilled",
      "promo_code": "LIVE-1",
      "earned_at": "2026-11-12T02:32:43.114Z"
    }
  ]
}

Field	Meaning
`referral_link`	The signup page address with the code. `null` when the signup page address is not set
`referrals`	The referrals that count
`referred`	The people whom the subscriber referred. `status` is `counted` or `pending`
`rewards`	The rewards that the subscriber earned

Status	Code	When
422	`invalid`	No `id` and no `email`
404	`not_found`	No subscriber with this id or email in the channel

Earned rewards

cURL

curl "https://your-broadcast-server/api/plugins/broadcast.referrals/fulfillment?status=pending" \
  -H "Authorization: Bearer YOUR_TOKEN"

Parameter	Rule
`status`	Optional. `pending`, `fulfilled` or `ignored`
`email`	Optional. Rows whose subscriber email has this text
`page`	Optional. The first page is `0`. A page has 25 rows

JSON

{
  "rows": [
    {
      "key": "earned:8205549236885:3141695:2",
      "subscriber_id": 3141695,
      "email": "ada@example.com",
      "reward_id": "2",
      "reward_name": "10% off",
      "required": 5,
      "status": "pending",
      "promo_code": "",
      "earned_at": "2026-11-12T02:32:43.114Z"
    }
  ],
  "matched": 1,
  "page": 0,
  "pages": 1
}

The rows are newest first. matched is the number of rows of all pages. The list reads the newest 1,000 earned rewards.

A status that is not in the list gets 422 invalid.

Mark a reward

Use the key of a row to set its status, for example after your shop sent the reward.

cURL

curl -X POST https://your-broadcast-server/api/plugins/broadcast.referrals/fulfill \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "key": "earned:8205549236885:3141695:2", "status": "fulfilled" }'

The answer is 200 with the row and its new status.

Status	Code	When
422	`invalid`	`status` is not `pending`, `fulfilled` or `ignored`
404	`not_found`	No earned reward has this `key`

Errors

An error answer has this shape:

JSON

{ "error": { "code": "invalid", "message": "Give id or email." } }