Campaign

Overview

A Campaign is a single coherent media plan owned by an Advertiser. Every campaign carries a mode: discovery, performance, or directed. Managed campaigns define flight dates, budget, optimization goals, audiences, creative requirements, and (after execution) the resulting media buys with publishers. A connected-account campaign is instead a read-only projection of one storefront-managed media buy. Its directed mode is a deprecated compatibility value; use management: "tracked" to identify the projection. In v2, the campaign is the focal object. For platform-managed campaigns, discovery sessions, products, creatives, audiences, frequency caps, and pacing schedules attach to it, and execution turns selected products into one or more media buys per sales agent. Tracked connected-account campaigns do not execute: subscription projects one existing upstream campaign into one campaign shell and one media buy. An external AdCP client calling an Interchange-hosted storefront creates a directed buyer campaign when that alpha is enabled: the task addresses one storefront and the storefront manages execution. Interchange anchors the contract, governance, durable journal, and dual-key media-buy identity before dispatch, then records accepted commitments and delivery on its ledger. The commercial envelope does not add a cross-storefront management layer. See How Interchange uses AdCP.

routingType is legacy compatibility metadata, not a campaign model. It is derived server-side on each media buy and currently records platform composition (DECISIONED) versus official sales-adapter execution (ROUTED). A third-party sales agent or finished-product/pass-through source remains DECISIONED. You do not set it. Campaign mode, bring-your-own buyer agent, protocol endpoint, execution path, and settlement method are independent concerns and must not be inferred from this field.

Choosing a mode for a named storefront

Naming one storefront or ad platform does not determine campaign mode by itself. If the request is simply “buy TikTok” or “buy Meta,” first clarify which system should remain the campaign source of truth:

A connected-account projection returns mode: "directed" when the seller or ad platform remains authoritative for a single one-to-one media buy. It is tracked and read-only; create the upstream campaign in the seller platform.
Choose discovery when Interchange manages product selection from a buyer brief. A discovery search may be scoped to one named storefront and still remain platform-managed. After selection and confirmation, launch it with execute_campaign.
Choose performance when Interchange allocates across sellers toward an objective. performanceConfig is required for this mode and is not accepted in discovery mode.

Campaign mode is fixed for normal updates. Adding performanceConfig to an existing discovery campaign is rejected rather than converting it to performance mode. To repair or retire an existing performance configuration, send performanceConfig: null; clearing it returns the campaign to discovery mode. Campaigns on connected seller accounts documents the read-only subscribe, mirror, refresh, and delivery lifecycle.

Key fields

Field	Type	Notes
`campaignId`	string	Stable campaign identifier
`mode`	enum	`discovery`, `performance`, or `directed` (the `directed` value is a deprecated compatibility value — read `management` for what the platform does with the campaign)
`management`	enum	`tracked` (mirrored from a connected seller account the platform did not set up; read-only shell) or `managed` (uses the canonical Interchange buyer lifecycle)
`advertiserId`	string	Owning advertiser
`name`	string	Campaign name (max 255)
`status`	enum	`DRAFT`, `ACTIVE`, `PAUSED`, `COMPLETED`, `CANCELED`, `ARCHIVED`
`flightDates`	object	`{ startDate, endDate }` ISO dates
`budget`	object	`{ total, currency, dailyCap?, pacing? }`. Gross — fee-inclusive, like every buyer budget. See Budgets and fees
`allocatedBudget`	number	Sum of active media buy budgets, plus delivered spend (all-in, at each buy’s locked fee terms) on ended or archived media buys — gross, the same denomination as `budget.total`
`unallocatedBudget`	number	`budget.total - allocatedBudget` — room left for new media buys. Can go negative when delivered spend on ended buys exceeds `budget.total`
`pacingPeriods`	object	Optional time-windowed pacing schedule with weight or budget mode
`constraints`	object	Channel filter plus AdCP-shaped targeting overlay (geo, language, device). Targeting fields flow into every media-buy package: include lists intersect with package-level targeting, exclude lists union.
`performanceConfig`	object	Optimization goals (event-based or metric-based)
`optimizationApplyMode`	`AUTO` \| `MANUAL`	Inherits advertiser default if unset
`audiences`	array	Target and suppress audiences
`mediaBuys`	array	Spawned at execution for platform-managed campaigns; exactly one mirrored upstream buy for a directed campaign
`creativeFormats`	object	`{ required, covered, missing }` — surfaces formats still needing creatives
`discoveryId`	string	Discovery session feeding product selection (DRAFT only)
`productCount`	number	Selected products (DRAFT only — after execute, products are inside media buys)
`frequencyCaps`	array	Buyer-side caps for this campaign

Platform-managed lifecycle

The steps below apply to managed discovery and performance campaigns. A tracked connected-account campaign has no DRAFT planning or execute step. Its mirror can be refreshed read-only. See Campaigns on connected seller accounts (alpha) for its connect → map → subscribe → mirror lifecycle. An inbound external-AdCP campaign is also platform-managed, but the external client performs the AdCP media-buy lifecycle directly; it does not separately call the buyer API’s execute_campaign. Its alpha create is anchored before seller dispatch. Campaign-spine update and cancellation support are not yet part of that alpha.

DRAFT — plan and configure

Create the campaign with flightDates, budget, and optional brief/constraints. Attach a discovery session, select products, attach audiences, configure pacing periods.

Upload creatives

Use GET /api/v2/buyer/campaigns/:campaignId/creatives/templates to see required formats, then upload manifest-based creatives via POST /api/v2/buyer/campaigns/:campaignId/creatives/create (multipart). Listing manifests is GET /api/v2/buyer/campaigns/:campaignId/creativeManifest. Inspect creativeFormats.missing to confirm coverage.

Execute → ACTIVE

POST /api/v2/buyer/campaigns/:id/execute launches a DRAFT (or COMPLETED) campaign — it creates one media buy per sales agent for each selected product, packages them per pacing period, and submits to ADCP. The campaign transitions DRAFT → ACTIVE. If submission fails and a media buy remains DRAFT, retrying execute submits that same buy without rebuilding it from discovery, so corrected per-buy settings remain intact.

PAUSE / resume

POST /api/v2/buyer/campaigns/:id/pause halts spend across all media buys. To resume a PAUSED campaign, call POST /api/v2/buyer/campaigns/:id/reactivate — this is a separate endpoint from execute and is the only way to bring a paused campaign back to ACTIVE.

COMPLETED

Reaching flightDates.endDate or full delivery transitions the campaign to COMPLETED.

Common operations

Create a campaign

This operation creates a managed campaign. To track a seller-owned campaign, create it in the connected platform and subscribe that account’s read-only mirror.

curl -X POST https://api.interchange.io/api/v2/buyer/campaigns \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "advertiserId": 12345,
    "name": "Q2 2026 — Tech Launch",
    "flightDates": { "startDate": "2026-05-15T00:00:00Z", "endDate": "2026-07-15T23:59:59Z" },
    "budget": { "total": 100000, "currency": "USD", "pacing": "even" },
    "brief": "Premium video for tech-savvy professionals",
    "constraints": {
      "channels": ["ctv", "video"],
      "geo_countries": ["US", "CA"],
      "geo_metros": [{ "system": "nielsen_dma", "values": ["501", "803"] }],
      "language": ["en"]
    }
  }'

{
  "advertiserId": 12345,
  "name": "Holiday Heavy-Up",
  "flightDates": { "startDate": "2026-11-01T00:00:00Z", "endDate": "2026-12-31T23:59:59Z" },
  "budget": { "total": 250000, "currency": "USD" },
  "pacingPeriods": {
    "mode": "weight",
    "periods": [
      { "label": "Pre-Black Friday", "start": "2026-11-01T00:00:00Z", "end": "2026-11-26T23:59:59Z", "weight": 1.0 },
      { "label": "Black Friday / Cyber Monday", "start": "2026-11-27T00:00:00Z", "end": "2026-12-02T23:59:59Z", "weight": 3.0 },
      { "label": "Holiday push", "start": "2026-12-03T00:00:00Z", "end": "2026-12-31T23:59:59Z", "weight": 1.5 }
    ]
  }
}

List / get campaigns

curl "https://api.interchange.io/api/v2/buyer/campaigns?advertiserId=12345&status=ACTIVE" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321 \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Add mode=discovery, mode=performance, or mode=directed to filter the shared campaign list without splitting reporting into separate resources. The list defaults to the live working set — every non-terminal status (ACTIVE, DRAFT, PAUSED) across both management states, so anything that could still spend shows up by default while terminal history does not. Pass explicit statuses or status=ALL to reach completed, canceled, or archived campaigns; add management=managed or management=tracked to narrow by who operates the campaign. Tracked scale belongs to the connected-account relationship rollup, not the ambient list: a subscribed account may mirror thousands of historical campaigns. LIST returns each campaign in a compact summary shape (identity, mode, status, flight dates, flattened budget, and product count). Directed summaries also carry provider and mirror freshness. Use GET /campaigns/{id} for the full mode-specific resource. Platform-managed details include brief, audiences, creative format coverage, budget allocation, pacing, performance config, and frequency caps; directed details project the single upstream media buy and its packages.

Auto-select products

With a discovery session, let Scope3 pick a balanced product set from decisioned inventory:

curl -X POST https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321/auto-select-products \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "maxProducts": 8, "minBudgetPerProduct": 2500 }'

Iterate with ADCP-style refinement:

{
  "refine": [
    { "scope": "request", "ask": "more video, less display" },
    { "scope": "product", "id": "prod_xyz789", "action": "more_like_this" },
    { "scope": "product", "id": "prod_xyz790", "action": "omit" }
  ]
}

Execute / pause / reactivate

# Launch a DRAFT (or COMPLETED) campaign — turns selected products into media buys and submits to ADCP
curl -X POST https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321/execute \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "debug": false }'

# Pause every media buy on the campaign
curl -X POST https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321/pause \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

# Resume a PAUSED campaign
curl -X POST https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321/reactivate \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

The execute response reports success, previousStatus, newStatus, and structured errors[] when individual media buy submissions fail. Pass debug: true to surface the raw ADCP request/response payloads in error details.

execute and reactivate are distinct endpoints. execute launches a DRAFT or COMPLETED campaign for the first time (or relaunches it). reactivate is the only way to bring a PAUSED campaign back to ACTIVE.

Update a running campaign

PUT /api/v2/buyer/campaigns/:id accepts partial updates. The mediaBuys[] array on update lets you act on individual media buys in one call:

{
  "mediaBuys": [
    {
      "action": "update",
      "mediaBuyId": "mb_abc123",
      "packages": [{ "packageId": "pkg_1", "budget": 15000, "pacing": "asap" }],
      "optimizationGoals": [
        { "kind": "metric", "metric": "completed_views", "target": { "kind": "cost_per", "value": 0.08 } }
      ]
    },
    { "action": "cancel", "mediaBuyId": "mb_def456", "reason": "underperforming" }
  ]
}

Always confirm optimizationGoals with the buyer before changing them — silent goal changes break optimization continuity.

When the update payload includes pacingPeriods, the response also contains a pacingCascadeResult block summarizing the per-media-buy outcome of pushing appended periods to live media buys. See the Pacing Periods guide for the response shape, append-only rules, and unsupported-agent fallback.

Live ADCP status

curl https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321/media-buy-status \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

This polls the sales agents directly and persists any status changes. Useful right after execution while waiting on publisher approvals.

Media buys and packages

Media buys are not a directly-creatable resource — they’re spawned by the platform when a campaign executes. Each media buy represents one ADCP transaction with one sales agent. You read their status and tune them via the campaign update endpoint. Hierarchy: Campaign → Media Buy (one per sales agent) → Package (one per product per pacing period) → Delivery.

Media buy status

status is one of DRAFT, PENDING_APPROVAL, INPUT_REQUIRED, ACTIVE, PAUSED, COMPLETED, CANCELED, FAILED, REJECTED, ARCHIVED. For multi-agent campaigns, the surfaced status is the most restrictive across agents — e.g. one ACTIVE and one PENDING_APPROVAL reports as PENDING_APPROVAL. INPUT_REQUIRED indicates a seller needs additional information before approval can proceed. Status updates flow via:

Webhooks from sales agents (preferred — near-real-time)
Polling via GET /api/v2/buyer/campaigns/:campaignId/media-buy-status, which queries each agent and persists changes

Optimization goals at the media-buy level

Goals are applied to every package in a media buy at execution time. Each goal is either event-based or metric-based:

{
  "kind": "event",
  "event_sources": [
    { "event_source_id": "website_pixel", "event_type": "purchase", "value_field": "value" }
  ],
  "target": { "kind": "cost_per", "value": 25.0 }
}

{
  "kind": "metric",
  "metric": "completed_views",
  "target": { "kind": "cost_per", "value": 0.08 }
}

Target kind	Meaning
`cost_per`	Target CPA (events) or CPM-like rate (metrics)
`per_ad_spend`	Target ROAS — value per dollar spent (events only)
`maximize_value`	No target — maximize total event value within budget
`threshold_rate`	Maintain a minimum rate of the metric (metrics only)

Supported metrics: clicks, views, completed_views, viewed_seconds, attention_seconds, attention_score, engagements, follows, saves, profile_visits, reach. For a reach or CPM-style goal, target metric: "reach" with a required reach_unit (individuals, households, devices, accounts, cookies, or custom) and an optional target_frequency — see Optimization goals for the full shape.

Packages

When a media buy executes, products turn into packages — one per product, multiplied by the number of pacing periods. Each package carries its own budget, pacing strategy (even, asap, front_loaded), bid price, flight start/end dates, and optimization goals. Delivery metrics roll up per-package: impressions, spend, clicks — these are reported rollups, not valid optimization_goals.metric targets.

Updating media buys via the campaign update endpoint

Use PUT /api/v2/buyer/campaigns/:id with the mediaBuys[] array. Allowed actions: update (default — modify), cancel (cancel running), delete (archive).

{
  "mediaBuys": [
    {
      "action": "update",
      "mediaBuyId": "mb_abc123",
      "packages": [
        { "packageId": "pkg_1", "budget": 15000, "pacing": "even" }
      ],
      "optimizationGoals": [
        { "kind": "metric", "metric": "completed_views", "target": { "kind": "cost_per", "value": 0.08 } }
      ],
      "updated_reason": "Mid-flight optimization based on early performance"
    }
  ]
}

{
  "mediaBuys": [
    { "action": "cancel", "mediaBuyId": "mb_abc123", "reason": "underperforming vs threshold" }
  ]
}

{
  "mediaBuys": [
    {
      "action": "cancel",
      "mediaBuyId": "mb_abc123",
      "packageIds": ["pkg_2"],
      "reason": "format not supported on this device mix"
    }
  ]
}

Creative attachment to a media buy

Omitting creative_ids leaves a media buy’s existing creative assignments unchanged. Pass creative_ids on a mediaBuys[] entry only when you intend to replace or clear its assignments.

Replace creatives for one media buy

{
  "mediaBuys": [
    {
      "action": "update",
      "mediaBuyId": "mb_abc123",
      "creative_ids": ["cr_video_15s", "cr_video_30s"]
    }
  ]
}

Omit creative_ids to leave existing assignments unchanged; no creative data is fetched, validated, synced, or forwarded.
"creative_ids": [] explicitly clears all creatives from the media buy.
Each ID must already be linked to the campaign and match a format accepted by the media buy’s products. Otherwise the update fails with a validation error — the field is not silently filtered.
creative_ids is only valid with action: "update". It is rejected with cancel or delete.

Cascade behavior

Campaign pause halts every media buy and package
Campaign reactivate brings them back to ACTIVE (post-flight if dates allow)
Creative manifest update re-syncs to every media buy that uses the format
Property list update propagates to packages without a full re-execute
Frequency caps on the campaign or advertiser are enforced across all media buys

Failures and debug

When a media buy fails to execute (publisher rejection, ADCP error), POST /api/v2/buyer/campaigns/:id/execute returns structured errors[]:

{
  "success": false,
  "errors": [
    {
      "mediaBuyId": "mb_abc123",
      "salesAgentId": "agent_xyz",
      "message": "Sales agent returned 422: invalid format for product"
    }
  ]
}

Pass debug: true on execute to include the full ADCP request, response, and A2A debug logs in each error entry.

Pacing periods

pacingPeriods defines time-windowed spend intensity within the campaign flight. Two modes:

weight — relative weights (e.g. 3.0 = 3x normal); budget is distributed proportionally
budget — explicit dollar amount per period

Gaps between periods are treated as pauses (no spend). On execute, each product becomes one package per period with proportional budget.

Pacing periods can only be modified on DRAFT campaigns. After execution, the package split is locked in. See the pacing periods workflow guide for full mode-by-mode examples.

Frequency caps

Buyer-side frequency caps configured on the campaign are enforced by Scope3 across all publishers in the campaign — distinct from publisher-side caps that live in package overlays.

"frequencyCaps": [
  { "max_impressions": 5, "window": { "interval": 7, "unit": "days" } }
]

When frequencyCaps is provided on update, it replaces all existing non-archived caps. See Frequency caps for the full configuration surface.

Routing compatibility metadata

routingType is a server-derived compatibility field on each media buy. It describes the current execution implementation; it is never a client input and there is no campaign-level routing type.

	DECISIONED	ROUTED
Current execution path	Interchange composition	Official sales adapter
Optimization in the current implementation	Interchange allocates and optimizes	Pass-through; no Interchange optimization
Credentials in the current implementation	Platform-managed	The buyer’s connected account
Product selection	Auto-select + manual	Manual
Derived from	Non-adapter storefront	Adapter storefront
Compatibility use	Managed storefront inventory	Existing connected platform account

Today an official sales-adapter buy is recorded as ROUTED; normal storefront composition and third-party sales-agent/pass-through source treatment are recorded as DECISIONED. Do not use this field to infer directed campaign mode, BYOA, AdCP connectivity, or who clears payment. Settlement is exposed separately on seller booking surfaces.

Creative

Manifest-based creatives uploaded under the campaign

Pacing periods

Time-windowed spend intensity

Frequency caps

Buyer-side cross-publisher caps

Getting Started

Advertisers

Campaigns

Product Discovery

Webhooks

Creatives

Signals & Brand

Audiences & Inventory

Measurement & Conversions

Reporting & Activity

Planning & Governance

Connections

Account & Billing

Overview

Choosing a mode for a named storefront

Key fields

Platform-managed lifecycle

Common operations

Create a campaign

List / get campaigns

Auto-select products

Execute / pause / reactivate

Update a running campaign

Live ADCP status

Media buys and packages

Media buy status

Optimization goals at the media-buy level

Packages

Updating media buys via the campaign update endpoint

Creative attachment to a media buy

Cascade behavior

Failures and debug

Pacing periods

Frequency caps

Routing compatibility metadata

Creative

Pacing periods

Frequency caps

​Overview

​Choosing a mode for a named storefront

​Key fields

​Platform-managed lifecycle

​Common operations

​Create a campaign

​List / get campaigns

​Auto-select products

​Execute / pause / reactivate

​Update a running campaign

​Live ADCP status

​Media buys and packages

​Media buy status

​Optimization goals at the media-buy level

​Packages

​Updating media buys via the campaign update endpoint

​Creative attachment to a media buy

​Cascade behavior

​Failures and debug

​Pacing periods

​Frequency caps

​Routing compatibility metadata

​Related concepts

Creative

Pacing periods

Frequency caps

Overview

Choosing a mode for a named storefront

Key fields

Platform-managed lifecycle

Common operations

Create a campaign

List / get campaigns

Auto-select products

Execute / pause / reactivate

Update a running campaign

Live ADCP status

Media buys and packages

Media buy status

Optimization goals at the media-buy level

Packages

Updating media buys via the campaign update endpoint

Creative attachment to a media buy

Cascade behavior

Failures and debug

Pacing periods

Frequency caps

Routing compatibility metadata

Related concepts