Campaigns
The core referral object — qualification gate plus reward configuration — and its lifecycle.
A campaign is an individual referral program: one object that pairs a qualification gate (what a referred user must do for the referral to count) with a reward configuration (what happens when they do). Every referral link, referral, and reward belongs to exactly one campaign. Most of our customers run only one single campaign.
Anatomy of a campaign
| Field | What it does |
|---|---|
name | Display name shown in the dashboard and on hosted offer pages. |
status | Lifecycle state: draft, active, paused, or archived. |
qualification | The Qualification Gate — criteria you set in the Invitebase dashboard (no code) to determine when a referral is accepted. |
reward | An array of Reward Configurations, one per recipient: method, amount, caps, milestone thresholds, expiry. One entry (the referrer) is single-sided; add a second entry for the referred user to make the campaign two-sided. |
mode / livemode | Whether the campaign lives in test or live mode. Set by the API key that created it, never by the request body. See Environments. |
Both the qualification gate and the reward configuration are validated at write time. Alongside these two, a campaign carries settings for the edge cases of who gets in, configured in the Campaigns Builder: eligibility rules that decide whether a referred user can qualify at all — new users only, an account-age limit, prior paid-subscription history — checked before the gates run, and an optional grace period that lets a code applied within N hours after signup still attribute.
Campaign lifecycle
| Status | Behavior |
|---|---|
draft | Being configured in the dashboard. Generates no links, attributes no referrals. Campaigns created via the API start active unless you pass status. |
active | Links resolve, clicks attribute referrals, gates evaluate, rewards fulfill. |
paused | Existing links stop attributing new referrals. Referrals already in flight keep evaluating and fulfilling — pausing stops new entries, it doesn't strand people who already qualified. |
archived | Terminal. The campaign is hidden from active lists and its links resolve to a generic page. DELETE /v1/campaigns/{id} archives; nothing is ever hard-deleted, so history and analytics stay intact. |
Manage the lifecycle from the Campaigns section of the dashboard or via PATCH /v1/campaigns/{id} with a status.
Test campaigns vs. live campaigns
Campaigns are mode-scoped like everything else: create a campaign with a test key and it exists only in test mode, where you can simulate the whole loop — synthetic events, fake-funded balance, sandbox payouts — without billing or money movement. When the config is right, promote it from the dashboard, which copies the qualification gate and reward configuration into a new live campaign. Test and live campaigns never share links, referrals, or data.
Editing a campaign
Campaigns aren't versioned. When you edit a campaign's gate or reward, the change takes effect immediately and applies to everyone immediately — including referrals already in flight.
- Rewards already paid out never change. A fulfilled reward stands, whatever you edit afterward.
- Pending rewards are re-evaluated against the new criteria. A referral that hasn't been fulfilled yet is measured against the campaign's current gate and reward — so tightening a gate can stop a not-yet-paid referral from qualifying, and changing a reward changes what an unpaid referral will receive.
So when you edit an active campaign, paid-out rewards are safe, but anything still pending follows the new rules the moment you save.
Reading campaign state at runtime
Client SDKs can fetch a campaign's public shape — copy, reward summaries, and the current user's progress. You can use this information to promote referrals, and build headless UI for your referral program - without a server. See the SDK references for getReferralLink(campaignId) and the campaign-info helpers.