Campaign API

Complete API reference for campaign management and participant operations.

Base Endpoint

/api/v1/campaigns

List Campaigns

Get a paginated list of campaigns.

GET /api/v1/campaigns

Query Parameters

Parameter	Type	Description
status	string	Filter by status (draft, active, ended)
type	string	Filter by type (promotion, challenge, event)
date_from	string	Filter from date
date_to	string	Filter to date
page	integer	Page number
limit	integer	Items per page

Example Response

{
  "data": [
    {
      "id": "camp_123",
      "name": "Summer Sale 2024",
      "description": "Special summer promotion",
      "type": "promotion",
      "status": "active",
      "start_date": "2024-06-01T00:00:00Z",
      "end_date": "2024-08-31T23:59:59Z",
      "target_segment": "all",
      "participant_count": 1250,
      "created_at": "2024-05-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

Get Campaign

Get campaign details.

GET /api/v1/campaigns/{campaign_id}

Example Response

{
  "data": {
    "id": "camp_123",
    "name": "Summer Sale 2024",
    "description": "Special summer promotion",
    "type": "promotion",
    "status": "active",
    "start_date": "2024-06-01T00:00:00Z",
    "end_date": "2024-08-31T23:59:59Z",
    "target_segment": {
      "id": "seg_123",
      "name": "Gold Members"
    },
    "reward": {
      "type": "discount",
      "value": 20,
      "unit": "percent"
    },
    "rules": {
      "min_purchase": 100,
      "max_uses": 1
    },
    "participant_count": 1250,
    "conversion_rate": 0.35,
    "created_at": "2024-05-15T10:00:00Z"
  }
}

Create Campaign

Create a new campaign.

POST /api/v1/campaigns

Request Body

{
  "name": "Summer Sale 2024",
  "description": "Special summer promotion",
  "type": "promotion",
  "start_date": "2024-06-01T00:00:00Z",
  "end_date": "2024-08-31T23:59:59Z",
  "target_segment_id": "seg_123",
  "reward": {
    "type": "discount",
    "value": 20,
    "unit": "percent"
  },
  "rules": {
    "min_purchase": 100,
    "max_uses": 1,
    "per_customer_limit": 1
  },
  "content": {
    "banner": "https://...",
    "terms": "Terms and conditions..."
  }
}

Example Response

{
  "data": {
    "id": "camp_123",
    "name": "Summer Sale 2024",
    "status": "draft",
    "created_at": "2024-05-15T10:00:00Z"
  }
}

Update Campaign

Update campaign details.

PATCH /api/v1/campaigns/{campaign_id}

Request Body

{
  "name": "Summer Sale 2024 - Updated",
  "end_date": "2024-09-30T23:59:59Z"
}

Activate Campaign

Activate a draft campaign.

POST /api/v1/campaigns/{campaign_id}/activate

End Campaign

End an active campaign.

POST /api/v1/campaigns/{campaign_id}/end

Campaign Participants

Join Campaign

Customer joins a campaign.

POST /api/v1/campaigns/{campaign_id}/join

Request Body

{
  "customer_id": "cus_12345"
}

Example Response

{
  "data": {
    "id": "part_123",
    "campaign_id": "camp_123",
    "customer_id": "cus_12345",
    "status": "active",
    "joined_at": "2024-06-01T10:00:00Z",
    "reward_claimed": false
  }
}

Get Campaign Participants

Get list of campaign participants.

GET /api/v1/campaigns/{campaign_id}/participants

Query Parameters

Parameter	Type	Description
status	string	Filter by status (active, completed, dropped)
page	integer	Page number
limit	integer	Items per page

Example Response

{
  "data": [
    {
      "id": "part_123",
      "customer": {
        "id": "cus_12345",
        "name": "John Doe",
        "tier": "gold"
      },
      "status": "active",
      "progress": {
        "current": 3,
        "target": 5,
        "percentage": 60
      },
      "joined_at": "2024-06-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1250
  }
}

Get Customer Campaigns

Get campaigns a customer has joined.

GET /api/v1/customers/{customer_id}/campaigns

Query Parameters

Parameter	Type	Description
status	string	Filter by status (active, completed, ended)

Campaign Analytics

Get Campaign Performance

Get campaign performance metrics.

GET /api/v1/campaigns/{campaign_id}/analytics

Query Parameters

Parameter	Type	Description
date_from	string	Filter from date
date_to	string	Filter to date
group_by	string	Group by (day, week, month)

Example Response

{
  "data": {
    "campaign_id": "camp_123",
    "metrics": {
      "participants": 1250,
      "conversions": 438,
      "conversion_rate": 0.35,
      "revenue": 125000,
      "average_order_value": 285.39
    },
    "by_date": [
      {
        "date": "2024-06-01",
        "participants": 50,
        "conversions": 18,
        "revenue": 5000
      }
    ]
  }
}