Campaigns

CutX campaigns let sellers launch ads on Meta, TikTok, and Google Ads directly from the platform.

Campaign Lifecycle

draft → active → paused → active → completed
  │                │
  └→ canceled      └→ canceled

Status	Description
draft	Campaign created but not yet launched
active	Live on the ad platform, spending budget
paused	Temporarily stopped, can be resumed
completed	Budget exhausted or end date reached
canceled	Manually stopped, cannot be resumed

Platform Adapters

Each ad platform has a dedicated adapter implementing a common interface:

Platform	API	Capabilities
Meta	Graph API v21.0	Facebook + Instagram ads
TikTok	Business API v1.3	TikTok feed ads
Google Ads	Ads API v17	Search + Display campaigns

All adapters support:

• createCampaign() — create campaign, ad sets, and ads
• pauseCampaign() / resumeCampaign() — lifecycle control
• getSpend() — fetch spend and performance data
• uploadCreative() — upload images or videos as ad creatives

Platform Connections

Before launching campaigns, users must connect their ad platform accounts via OAuth:

GET /api/campaigns/connect/meta
GET /api/campaigns/connect/tiktok
GET /api/campaigns/connect/google

These initiate OAuth flows that store access/refresh tokens in ad_platform_connections. Tokens are encrypted at rest and refreshed automatically.

Ad Spend Fees

CutX charges a percentage fee on ad spend managed through the platform:

Subscription Tier	Fee Rate
Free	6%
Starter	6%
Pro	5%
Agency	4%

Fees are calculated during the daily analytics sync and recorded in the ad_spend_fees table.

Example: A Pro-tier user spending $100/day on Meta ads pays $5/day in platform fees.

Analytics Sync

Campaign performance data is pulled daily from each platform and stored in campaign_analytics:

Metric	Description
impressions	Number of times the ad was shown
clicks	Number of clicks on the ad
spend	Amount spent in the user’s currency
conversions	Tracked conversion events
ctr	Click-through rate (clicks/impressions)
cpc	Cost per click (spend/clicks)
roas	Return on ad spend (revenue/spend)

The sync pulls the last 7 days of data on each run to capture any attribution updates from the ad platforms.

Campaign Assets

Each campaign can have multiple creative assets attached:

POST /api/campaigns/<id>/assets
Content-Type: application/json

{
  "asset_id": "uuid",
  "role": "primary"
}

Assets are generated through the generation system and linked to campaigns for deployment to the ad platform.