Campaigns API

Create and manage referral campaigns.

Campaigns define the rules for your referral program — reward triggers, amounts, and limits.

GET/v1/campaigns

List all campaigns for your organization.

Parameters

Name	Type	Required	Description
status	string	Optional	Filter by status: active, paused, archived
limit	number	Optional	Max results (default 20, max 100)

Response

{
  "data": [
    {
      "id": "camp_xxxxx",
      "name": "Summer Referral Program",
      "status": "active",
      "rewardTrigger": "signup",
      "referrerReward": { "type": "credit", "amount": 10 },
      "referredReward": { "type": "credit", "amount": 5 },
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

GET/v1/campaigns/:id

Get details for a specific campaign.

Parameters

Name	Type	Required	Description
id	string	Required	Campaign ID

Response

{
  "id": "camp_xxxxx",
  "name": "Summer Referral Program",
  "description": "Summer promotion with bonus rewards",
  "status": "active",
  "rewardTrigger": "signup",
  "referrerReward": {
    "type": "credit",
    "amount": 10,
    "currency": "USD"
  },
  "referredReward": {
    "type": "credit",
    "amount": 5,
    "currency": "USD"
  },
  "limits": {
    "maxReferralsPerUser": 50,
    "maxReferralsPerDay": 10
  },
  "attributionWindow": "7d",
  "stats": {
    "totalClicks": 1250,
    "totalConversions": 89,
    "totalRewardsIssued": 134
  },
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

POST/v1/campaigns

Create a new campaign.

Request Body

{
  "name": "Holiday Referral Bonus",
  "description": "Double rewards for the holidays",
  "rewardTrigger": "signup",
  "referrerReward": {
    "type": "credit",
    "amount": 20
  },
  "referredReward": {
    "type": "credit", 
    "amount": 10
  },
  "limits": {
    "maxReferralsPerUser": 100
  },
  "attributionWindow": "30d"
}

Response

{
  "id": "camp_yyyyy",
  "name": "Holiday Referral Bonus",
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z"
}

PATCH/v1/campaigns/:id

Update a campaign. Only specified fields are updated.

Parameters

Name	Type	Required	Description
id	string	Required	Campaign ID

Request Body

{
  "status": "paused",
  "referrerReward": {
    "amount": 15
  }
}

Response

{
  "id": "camp_xxxxx",
  "status": "paused",
  "updatedAt": "2024-01-15T10:30:00Z"
}