Chapter 15 — Campaigns

Campaigns are the top-level container under an ad account. They define budget, scheduling, and geographic targeting.

Endpoints

Method	Path	Purpose
GET	/campaigns	List campaigns.
POST	/campaigns	Create a campaign.
GET	/campaigns/{id}	Retrieve one campaign.
POST	/campaigns/{id}	Update a campaign (note: POST, not PATCH or PUT).
POST	/campaigns/{id}/activate	Set status to active.
POST	/campaigns/{id}/pause	Set status to paused.
POST	/campaigns/{id}/archive	Set status to archived (irreversible).
GET	/campaigns/{id}/insights	Query performance at campaign scope.

Create-campaign fields

Field	Type	Required	Notes
name	string	Yes	3–1000 chars, must include a non-space character.
description	string	No	—
start_time	integer	No	Unix seconds, between 946684800 and 4102444800. If omitted, campaign starts delivering immediately.
end_time	integer	No	Unix seconds, same range.
status	string	Yes	active or paused on create.
budget.lifetime_spend_limit_micros	integer	Yes	Minimum 1,000,000 (= $1.00 in USD accounts).
targeting.locations.countries	string[]	No	ISO country codes to include. If omitted, all countries are targeted.
targeting.excluded_locations.countries	string[]	No	ISO country codes to exclude.

Time and currency fields respect the ad account’s default timezone and currency (Chapter 14).

List parameters

Parameter	Type	Notes
limit	integer	1–500. Default 20.
after	string	Cursor for next page.
before	string	Cursor for previous page.
order	string	asc or desc.

Update behaviour

All fields are optional on update. If budget is included, send the full budget object — partial updates of budget are not supported. description, start_time, end_time, and targeting accept null to clear them. status accepts active, paused, or archived.

Example: create a US/Canada campaign

curl -X POST "https://api.ads.openai.com/v1/campaigns" 
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Spring launch",
    "description": "Promote the new productivity bundle.",
    "start_time": 1735689600,
    "end_time": 1738368000,
    "status": "active",
    "budget": { "lifetime_spend_limit_micros": 25000000 },
    "targeting": { "locations": { "countries": ["US", "CA"] } }
  }'

The lifetime spend limit 25000000 micros = $25 in a USD account.

Example response

{
  "id": "cmpn_101",
  "created_at": 1735689600,
  "updated_at": 1735689600,
  "name": "Spring launch",
  "description": "Promote the new productivity bundle.",
  "status": "active",
  "start_time": 1735689600,
  "end_time": 1738368000,
  "budget": { "lifetime_spend_limit_micros": 25000000 },
  "targeting": { "locations": { "countries": ["US", "CA"] } }
}

Default behaviour worth knowing

• No start_time → starts delivering immediately on active.
• No targeting.locations.countries → all countries are eligible. Combined with the eligibility matrix in Chapter 3, this means the campaign reaches every supported geography.
• No end_time → runs until the lifetime spend limit is exhausted.

For a Shopify brand running tightly scoped tests, set all three explicitly. Defaults are convenient for one-off campaigns but dangerous for budget pacing.