Skip to main content
POST
Create campaign

Authorizations

​
Authorization
string
header
required

API key or access token

Body

application/json

Request body for creating a discovery-mode campaign

​
advertiserId
integer
required

Advertiser ID that will own this campaign

Required range: 0 < x <= 9007199254740991
Example:

12345

​
name
string
required

Name of the campaign

Required string length: 1 - 255
Example:

"Q1 2025 Campaign"

​
flightDates
object
required

Campaign flight dates

​
budget
object
required

Campaign budget configuration

​
mode
enum<string>
required

"I have a brief; find it for me" — platform-managed. Optimization goals (performanceConfig) are allowed on any mode; they are hints, not a composition-ownership declaration.

Available options:
discovery
​
idempotencyKey
string

Optional retry key. Repeating the same create for this customer returns the first campaign.

Required string length: 1 - 200
​
operatorFees
object[]

The operator's fee on this campaign: at most one entry, as a decimal proportion of the gross budget (rate: 0.02 for 2%). Only a caller acting for the operator organisation, the parent of this account, may set it, and only when operator fees are enabled for that organisation, the account's media is invoiced to the operator, and the campaign has a budget. Each media buy created under the campaign afterwards locks the fee into its own terms.

Maximum array length: 1
​
brief
string

Natural language brief for product search context

Maximum string length: 5000
Example:

"Looking for premium video inventory targeting tech enthusiasts"

​
constraints
object

Campaign targeting constraints

​
channelGroups
object[]

Canonical buyer-declared inventory execution and reporting boundaries. REST clients send the fully expanded saved shape; /mcp/v3 save_campaign also accepts preset shorthand.

Required array length: 1 - 25 elements
​
storefrontIds
integer[]

Storefront IDs the campaign is limited to. When set, every discover_products run for this campaign auto-applies this filter — buyers do not need to resend it. Pass the IDs returned by list_storefronts. Highly encouraged so the campaign only sources inventory from sellers the buyer has chosen.

Maximum array length: 50
Required range: 0 < x <= 9007199254740991
Example:
​
discoveryId
string

Attach an existing discovery session to the campaign

Minimum string length: 1
Example:

"abc123-def456-ghi789"

​
productIds
string[]

Product IDs to pre-select from the discovery session (requires discoveryId)

Example:
​
audienceConfig
object

Audience targeting and suppression configuration. On create, listed audiences are attached to the campaign.

​
performanceConfig
object

Performance optimization configuration

​
optimizationApplyMode
enum<string>

Controls whether Scope3 AI model optimizations to media buys are applied automatically or require manual approval. If omitted, inherits the advertiser-level setting.

Available options:
AUTO,
MANUAL
​
catalogId
integer

ID of a catalog (from the advertiser catalogs list) to attach to this campaign. Only one catalog may be attached per campaign.

Required range: 0 < x <= 9007199254740991
Example:

42

​
pacingPeriods
object

Pacing schedule for the campaign. Defines time-based spend periods with varying intensity. In weight mode, budget is distributed proportionally by weighted days. In budget mode, explicit dollar amounts are set per period. Gaps between periods are treated as pauses (no spend). On execution, each product is split into one package per period with proportional budget.

​
utmConfig
object

Click-URL parameters for this campaign. An object with params and optional deleteMissing; campaign keys override advertiser keys with the same name. At campaign level a write is additive: it adds or updates the given keys and keeps the others, unless deleteMissing: true replaces the campaign set. Advertiser utmConfig is a plain array that always replaces the advertiser set. For one model at advertiser, campaign and creative level, and to suppress an inherited key with a null value, use V3 tracking.macroAdditions (save_advertiser, save_campaign) or macroAdditions (save_creative).

​
dataDelivery
object

Campaign-scoped data-delivery configuration. Groups Data Delivery Outputs that override advertiser-scoped delivery for the same dataDeliveryType. Distinct from media-buy reporting fields elsewhere in the API.

​
frequencyCaps
object[]

Buyer-side frequency cap configs to apply to this campaign, enforced via Scope3's cross-publisher exposure tracking on TMP-connected inventory. Closed-platform integrations (e.g. TikTok, Meta, Snap, and other adapter-based publishers) cannot honor this at their own request time — to cap frequency on one of those platforms' own native ad-serving, set targetingOverlay.frequency_cap on the product instead (see add_discovery_products / create_media_buys).

​
autonomy
object

Autonomy settings for this campaign. Controls who owns composition and brief updates. Set inventorySelection: "automatic" to let the platform optimizer pick inventory; the default is "manual".

Response

Create campaign

Response containing a single campaign

​
campaign
object
required

Campaign resource representation

​
warnings
string[]

Non-blocking advisories, such as a media buy that ended without delivering because its seller never started it.