Campaigns

Lifecycle guide for creating, activating, pausing, and cloning campaign experiences.

Audience: Growth and lifecycle teams operating campaigns across one or more sites.

Critical: Campaign runtime exposure happens through /api/v1/public/sites/:siteKey/campaigns and only eligible active campaigns are returned.

Widgets Experiments Revenue Analytics

Who This Page Is For

Use this page when you need an operational contract for campaign CRUD, publish lifecycle transitions, and metrics-aware campaign listing.

Quick Start (2-5 Minutes)

Create draft campaign

Create campaign with content, placement, and initial status controls.

POST /api/v1/campaigns

Review and publish

Move campaign from draft/scheduled to active delivery.

POST /api/v1/campaigns/:id/publish

Pause during incident window

Pause campaign instantly without deleting its history.

POST /api/v1/campaigns/:id/pause

Activate again

Re-enable a paused campaign after fixes or timing changes.

POST /api/v1/campaigns/:id/activate

Validate runtime delivery

Confirm expected campaigns are returned to storefront runtime.

GET /api/v1/public/sites/:siteKey/campaigns

Core endpoints

POST   /api/v1/campaigns
GET    /api/v1/campaigns
GET    /api/v1/campaigns/:id
PUT    /api/v1/campaigns/:id
POST   /api/v1/campaigns/:id/publish
POST   /api/v1/campaigns/:id/pause
POST   /api/v1/campaigns/:id/activate
POST   /api/v1/campaigns/:id/clone
DELETE /api/v1/campaigns/:id
GET    /api/v1/public/sites/:siteKey/campaigns

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`name`	Required	`string`	Campaign create/update	Campaign display name for operations and reporting.
`siteId`	Required	`uuid`	Campaign create	Site scope for campaign delivery and analytics.
`type`	Required	`WidgetType`	Campaign rendering	Campaign visual form (banner, popup, slide-in, etc.).
`contentJson or content`	Optional	`object`	Campaign rendering	Runtime copy and CTA content fields.
`startDate / endDate`	Optional	`ISO string`	Scheduling	Window where campaign can be considered eligible.
`priority`	Optional	`int`	Conflict resolution	Higher priority can win when placements overlap.
`segmentTargetingMode + segmentIds`	Conditional	`string + uuid[]`	Audience gating	Use for include/exclude audience controls.

List with metrics

GET /api/v1/campaigns?siteId=SITE_ID&withMetrics=true&days=30

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Create a campaign draft	POST /api/v1/campaigns	Initial create with validation and audit trail.
Push campaign live	POST /api/v1/campaigns/:id/publish	Explicit publish transition; avoids ambiguous status edits.
Temporary stop	POST /api/v1/campaigns/:id/pause	Preserves campaign settings and historical metrics.
Re-run an existing campaign	POST /api/v1/campaigns/:id/activate	Restores delivery without creating duplicate records.
Create a variant quickly	POST /api/v1/campaigns/:id/clone	Keeps configuration baseline and reduces setup time.

Common Errors and Fixes

Campaign is active but not visible on storefront

Cause: Public guard checks failed (site verification, origin, or subscription) or targeting rules do not match page/user.

Fix: Validate site domain/origin, subscription state, page targeting, and segment filters.

Cannot publish campaign

Cause: User role lacks campaign publish permission.

Fix: Ensure account has campaign publish capability in RBAC settings.

Unexpected campaign ordering

Cause: Priority values conflict across multiple active campaigns.

Fix: Normalize priority strategy per placement zone.

Metrics list returns empty values

Cause: withMetrics requested without valid siteId filter.

Fix: Call list endpoint with both siteId and withMetrics=true.

Production Checklist

Campaign naming follows a stable convention (channel, objective, date).Required
Publish/pause workflows are used instead of ad hoc status mutation.Required
withMetrics queries are run with explicit siteId and days window.Required
Public campaign payload validated in production storefront context.Required
Retired campaigns are cloned only when intentional and traceable.Required

Email Campaign Audience Snapshot

Email campaign delivery uses send-time audience resolution and snapshot metrics.

Create/update endpoints: POST /api/v1/email/campaigns, PUT /api/v1/email/campaigns/:id
audienceConfig supports merged sources: manual_csv, newsletter, users
Segment filters are applied at send time via segmentTargetingMode + segmentIds
Snapshot fields are persisted on campaign: audienceSnapshotJson, audienceResolutionStatus, audienceResolvedAt
Contacts without segment identity are excluded from segment-filtered sends and counted in snapshot reasons
Backward compatibility: legacy recipients payload remains supported for manual/CSV workflows