Programmes

Statuses, qualification conditions, the four reward types, caps, tiers and A/B variants.

A programme belongs to an app. One programme per app can be live at a time; creating a second live programme is refused until you pause the first.

Statuses

Status	Meaning
`draft`	Being configured. No links are minted and nothing is attributed.
`live`	Running. Users can get links, and installs are attributed.
`paused`	Existing referrals still qualify and pay, but no new ones are created.
`ended`	Finished. Nothing new is attributed or qualified.

curl -X POST https://api.vouch.dev/v1/referral-programmes/rpg_123/status \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"status":"live"}'

Qualification conditions

Conditions sit on a variant and combine with AND. Every type below is supported.

Type	Satisfied when
`install`	The invitee's install is attributed.
`account_created`	The invitee identifies with your own user id, or your app reports the event.
`custom_event`	An event you send arrives, optionally filtered on its properties.
`trial_started`	A `trial` conversion is reported for the invitee.
`first_purchase`	The invitee's first `purchase` conversion is reported.
`purchase_over`	A purchase at or above an amount you set, in minor units with a currency.
`subscription_active_days`	The invitee has held an active subscription for a number of days.

{
  "all": [
    { "type": "account_created" },
    { "type": "purchase_over", "amount_minor": 2000, "currency": "GBP" }
  ]
}

Vouch learns about trials, purchases and refunds from conversions you report. See Attribution.

Rewards

A programme can reward the inviter, the invitee, or both, with different conditions per side. There are four types.

Type	What it does	Fields
`credit`	A number of your own units, such as credits or free days.	`amount`, `unit`
`coupon`	Claims one code from a pool you upload. A code is never handed out twice.	`pool`
`entitlement`	Grants a feature or extends a subscription.	`key`, `days`
`webhook`	Vouch records the reward and calls you; you fulfil it.	n/a

Add cost_minor and currency to any reward and Vouch will report what your programme costs. Without them it reports the quantity, which is still useful but cannot be compared across units.

{
  "type": "credit",
  "amount": 10,
  "unit": "credits",
  "cost_minor": 250,
  "currency": "GBP"
}

Caps and tiers

Caps stop a programme running away from you.

Cap	Limits
`per_inviter_per_period`	How many rewards one inviter can earn per `day`, `week` or `month`.
`programme_total`	How many rewards the programme will ever issue.
`per_invitee_lifetime`	How many times one invitee can be rewarded.

Tiers raise the inviter's reward once they have brought in enough people.

{
  "caps": {
    "per_inviter_per_period": { "count": 10, "period": "month" },
    "programme_total": 10000,
    "per_invitee_lifetime": 1
  },
  "tiers": [
    { "after_qualified": 5, "reward": { "type": "credit", "amount": 20, "unit": "credits" } }
  ]
}

A programme always has a variant keyed a. Add a variant keyed b and split the traffic to test one configuration against another. A participant is assigned to a variant once and stays there, so an inviter never sees their offer change.

curl -X PUT https://api.vouch.dev/v1/referral-programmes/rpg_123/variants \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"variants":[
        {"key":"a","traffic_percent":50,"conditions":{"all":[{"type":"first_purchase"}]},
         "inviter_reward":{"type":"credit","amount":10,"unit":"credits"}},
        {"key":"b","traffic_percent":50,"conditions":{"all":[{"type":"account_created"}]},
         "inviter_reward":{"type":"credit","amount":5,"unit":"credits"}}
      ]}'

Reports compare variants on invites sent, qualified rate and reward cost.

Codes

Each participant gets a code as well as a link, for people who type it in or read it aloud. The default alphabet leaves out characters that are misheard or misread: no 0 or O, no 1, I or L. Set code_length and code_alphabet per programme.

Codes are matched case-insensitively and ignore separators, so w3zy-epd8 and W3ZYEPD8 are the same code.

Coupon pools

Upload your own codes and a coupon reward will claim one per qualified referral.

curl -X POST https://api.vouch.dev/v1/referral-programmes/rpg_123/coupons \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"pool":"launch","codes":["SAVE-A1B2","SAVE-C3D4"]}'

The response reports how many were added, how many were duplicates and how many were rejected, plus the stock left in each pool. Claiming locks the row, so two referrals qualifying at the same instant cannot receive the same code.