Create campaign

POST /api/v2/buyer/campaigns For discovery and performance, creates a campaign in DRAFT status for the given advertiser. Flight dates and budget are required. Products, creatives, and audiences attach afterward. The legacy routingType field is not a campaign input; it is derived per media buy as temporary billing compatibility metadata from BillingParty. It is never a storefront or execution type and is independent of campaign mode, BYOA, and protocol connectivity. Execute the campaign later to turn it into live media buys. Buyer-owned labels are applied through V3 MCP save_campaign, not this REST create. See Dimensions and labels.

REST request

Every campaign budget is GROSS: budget.total is the all-in amount the buyer pays, with Apostra fee inside it. Every budget downstream is gross too — media buy and package budgets allocate against budget.total directly, and the media/fee split is derived per media buy at the fee terms locked when that buy is created (readable via its budget_breakdown — see Budgets and fees). There is no fee-model input at creation — the campaign object has no feeType field.

Request

curl -X POST https://api.apostra.com/api/v2/buyer/campaigns \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "advertiserId": 12345,
    "name": "Q2 2026 Tech Launch",
    "idempotencyKey": "campaign-q2-tech-launch-2026",
    "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 }
    ]
  }
}

Parameters

Field	Type	Required	Notes
`advertiserId`	number	Yes	Owning advertiser
`name`	string	Yes	Campaign name (max 255)
`idempotencyKey`	string	No	Retry key for campaign creation (1-200 characters). Reusing it for the same advertiser returns the first campaign.
`flightDates`	object	Yes	`{ startDate, endDate }`, ISO 8601 dates
`budget`	object	Yes	`{ total, currency?, dailyCap?, pacing? }`. `currency` defaults to the advertiser’s primary currency when omitted. `pacing` is `EVEN`, `ASAP`, or `FRONTLOADED`; every package inherits it unless its product line sets its own, and an unset pacing sends `even` (see Which pacing a package gets)
`brief`	string	No	Free-text plan brief used to guide product selection
`constraints`	object	No	`channels` filter plus AdCP targeting overlay: `geo_countries`, `geo_metros`, `language`. Send only metro codes in `geo_metros`; use `resolve_targeting_dimension` when the buyer provides a name such as “LA DMA”, and request `fields=geo_metro_names` on campaign reads when display labels are needed. Included labels return in `geo_metro_names`; excluded labels return in `geo_metro_names_exclude`.
`pacingPeriods`	object	No	Time-windowed pacing. `mode` is `weight` or `budget`; `periods[]` each carry `label`, `start`, `end`, and `weight` (weight mode)

Safe retries

Send an idempotencyKey when the client may retry after a timeout or lost response. The key is scoped to the authenticated customer and remains bound to the first campaign created for that advertiser. A replay returns that campaign instead of creating another one, even if the retried body contains different values. Generate a new key for a new campaign. Reusing a key for another advertiser returns 409 CONFLICT.

Response

{
  "campaign": {
    "campaignId": "cmp_987654321",
    "advertiserId": "12345",
    "name": "Q2 2026 Tech Launch",
    "status": "DRAFT",
    "flightDates": { "startDate": "2026-05-15T00:00:00Z", "endDate": "2026-07-15T23:59:59Z" },
    "budget": { "total": 100000, "currency": "USD", "pacing": "EVEN" },
    "optimizationApplyMode": "MANUAL",
    "createdAt": "2026-05-01T09:00:00Z",
    "updatedAt": "2026-05-01T09:00:00Z"
  }
}

The campaign is created in status: "DRAFT". campaign.campaignId is the stable identifier you pass to every sibling operation. Routing is decided per media buy at execution time — a campaign has no routing type of its own. When the request included a discoveryId, the response also carries productGroups, budgetContext, and summary from the discovery session.

Errors

400 VALIDATION_ERROR — missing required field, malformed flightDates, or non-positive budget.total.
409 CONFLICT — idempotencyKey was already used for another advertiser.
404 NOT_FOUND — advertiserId does not exist or is not visible to the authenticated account.

See Errors for the full error contract.

Campaign tasks

All campaign operations

Campaign overview

Fields, lifecycle, and concepts

Auto-select products

Populate a campaign from eligible storefront inventory

Execute campaign

Launch into media buys

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Create campaign

REST request

Request

Parameters

Safe retries

Response

Errors

Campaign tasks

Campaign overview

Auto-select products

Execute campaign

​REST request

​Request

​Parameters

​Safe retries

​Response

​Errors

​Related

Campaign tasks

Campaign overview

Auto-select products

Execute campaign

REST request

Request

Parameters

Safe retries

Response

Errors

Related