Paid Media Guide

ChatGPT Ads in 2026: The Complete Guide to Accounts, Targeting, Bidding and Measurement

OpenAI has shipped a complete advertising API: objectives, bid strategies, budget types, targeting, creative review, spend limits and insights. This is the media buyer's read on how it is structured, what it decides for you, and where the expensive mistakes are.

Distk Editorial Nov 2026 53 min read

The ChatGPT Ads API, formally the Advertiser API, runs at https://api.ads.openai.com with bearer authentication and one key per ad account. Structure is account, campaign, ad group, ad, with targeting on the campaign and bidding on the ad group. There are three objectives set as bidding_type (impressions, clicks, conversions) and three bid strategies (fixed_bid, maximize_clicks, maximize_conversions, the latter two branded Maximize Results), but only five valid combinations of objective, billing event and strategy. Maximize Results requires a daily budget, click billing, no explicit bid, no audience bid multipliers and a mandatory Idempotency-Key. Budgets and bids use micros at 1,000,000 per major currency unit, and impression bids are per impression, so a 60 USD CPM is 60000 micros. New resources are created paused and you activate from the ad upward. Campaign objective, the oCPC conversion event, a daily-to-lifetime budget change and an ad's parent ad group are all fixed after creation. Targeting sits at campaign level (geography, platform, custom audiences and context hints), conversion campaigns bill per click while optimising to a CPA bid, attribution runs on the Measurement Pixel plus the Conversions API with the oppref click ID passed back server-side, and agencies can batch changes through the Bulk API.

What Is the ChatGPT Ads API in 2026?

The ChatGPT Ads API, which OpenAI calls the Advertiser API, is the programmatic interface for creating and managing ads that appear inside ChatGPT. It handles campaigns, ad groups, ads, product feeds, conversion tracking and reporting. Requests go to https://api.ads.openai.com with a bearer token, and you create that key in the Settings page of Ads Manager at ads.openai.com.

This is a full ad platform rather than a placement you buy through someone else. It has objectives, bid strategies, budget types, geographic and platform targeting, audience inclusion and exclusion, creative review, spend limits, audit logs and an insights endpoint. If you buy media for a living, the useful question is not whether it works but which decisions it leaves you and which it takes away. This guide answers that, using only OpenAI's own documentation.

How Is a ChatGPT Ads Account Structured in 2026?

Four levels, each owning different settings. An ad account contains campaigns, each campaign contains ad groups, and each ad group contains ads. OpenAI's guidance is to configure each setting at the level that owns it, use separate campaigns when you need separate budgets, objectives or targeting, and use ad groups for different bid configurations, context hints or product sets.

Ad account
└── Campaign
    └── Ad group
        └── Ad
LevelWhat you configure hereWhat this means for a media buyer
Ad accountAdvertiser branding, currency, timezone, account access, spend limitsCurrency and timezone are creation-time choices and cannot be edited later.
CampaignObjective, budget, schedule, geographic and platform targeting, audience inclusion and exclusion, conversion eventsTargeting lives here, not on the ad group. One budget is shared across all its ad groups.
Ad groupBid strategy, context hints, audience bid multipliers, product setThis is your bidding and relevance layer.
AdCreative, image or product template, destination URLAn ad cannot be moved to another ad group after creation.

One structural constraint is worth planning around in 2026: targeting is a campaign-level setting. If you want two different geographies or two different audience definitions, that is two campaigns, and therefore two budgets. Teams used to building one campaign with many differently-targeted ad sets will need to restructure.

Why Does an Account Have Three Different Names?

Because they serve three audiences. OpenAI documents legal_name for the legal business name, account_name for the internal name shown in Ads Manager, and brand_name for the public advertiser name shown in ads. The response also includes name, which matches legal_name.

FieldPurposeWho sees it
legal_nameLegal business nameReview and billing context
account_nameInternal name shown in Ads ManagerYour team and your agency
brand_namePublic advertiser name shown in adsPeople seeing the ad in ChatGPT

For agencies the separation is useful. account_name can follow your internal client naming convention without affecting anything public. You can update the three names independently, and omitted names remain unchanged. One trap: the legacy name field sets all three to the same value, and OpenAI says not to combine it with the individual name fields.

How Do You Set Advertiser Branding?

Upload an icon, then apply the brand name, website and icon in one request. The icon must be JPEG, PNG or WebP at a minimum of 256 by 256 pixels, uploaded with purpose=account_favicon.

curl -X POST "https://api.ads.openai.com/v1/upload"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -F "file=@/path/to/favicon.png"   -F "purpose=account_favicon"
curl -X POST "https://api.ads.openai.com/v1/ad_account/brand"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -H "Content-Type: application/json"   -d '{
    "brand_name": "Acme",
    "url": "https://example.com",
    "favicon_file_id": "file_123"
  }'
The branding change that stops your ads in 2026

OpenAI states that changing the legal or public brand name pauses ad delivery until the account passes review. A rebrand, a typo correction or a client asking for a different display name mid-campaign all stop every ad in the account. Get the public name right before launch, and schedule any later change for a moment when a delivery pause is acceptable.

After any branding update, retrieve the account again and check its review state. OpenAI also notes that the returned preview_url is a preview of the advertiser icon and not a permanent asset URL, so do not store it as the durable source for that image.

Why Can an Active Account Still Not Deliver?

Because configured status and reviews are separate, and approved branding is only one requirement among several. OpenAI is explicit that an active account with approved branding can still have another outstanding account review, an exhausted spend limit, or campaign-level delivery issues. This is the single most common source of "everything is green but nothing is serving" confusion on a new account.

curl -G "https://api.ads.openai.com/v1/ad_account"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"
FieldWhat it tells you
statusWhether the account is configured as active or paused
review.statusBrand-review state
review.reasonReason for a brand-review issue, when available
account_integrity_review.review.statusA separate account-review state, when the object is returned

One interpretation rule matters. OpenAI states the response can omit account-integrity review information when no corresponding state is available, and that an omitted object should not be interpreted as an explicit approval or rejection. Absence is not a green light.

What Do Pausing and Activating the Account Actually Do?

Pausing stops delivery across every campaign in the account; activating allows eligible campaigns to deliver again. OpenAI recommends using account controls only when the change should apply to the whole account, and pausing a campaign, ad group or ad for anything narrower.

curl -X POST "https://api.ads.openai.com/v1/ad_account/pause"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"

curl -X POST "https://api.ads.openai.com/v1/ad_account/activate"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"

Two things activation does not establish, both stated in the documentation. It does not mean every campaign is active, every ad is approved, or every budget has capacity. And a pause does not rewrite child statuses, so you should not infer that campaigns were set to paused after an account pause. Retrieve the child resource if you need its configured state. For an agency's emergency stop, the account pause is the fastest single lever; for anything else, it is too blunt.

How Do Account Spend Limits Work?

Two mechanisms exist, and they sit alongside campaign budgets rather than replacing them. Date-range spend-limit windows cap total spending across all campaigns over a date range. Daily account limits, added in the changelog on 9 September 2026 for accounts on postpaid invoice billing, set a shared allowance across campaigns that renews at midnight in the account timezone. OpenAI notes that spend-limit windows are available only to some accounts.

Date-range spend-limit windows

curl -X POST "https://api.ads.openai.com/v1/ad_account/spend_limit_windows"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -H "Content-Type: application/json"   -d '{
    "start_date": "2026-10-01",
    "end_date": "2026-11-01",
    "amount_micros": 10000000000,
    "name": "October account limit",
    "io_id": "IO-123"
  }'

The example caps spending at 10,000 currency units. start_date is inclusive and end_date is exclusive, both interpreted in the account timezone. The optional io_id is a useful hook for agencies that reconcile spend against insertion orders.

Window ruleWhat OpenAI documents
OverlapWindows cannot overlap
Future windowsYou can schedule up to 60
Active window start dateCannot be changed
Reducing the amountCannot go below spending that has already occurred
Completed windowsCannot be edited or deleted
Deleting or raising an exhausted active limitCan allow delivery to resume if nothing else blocks it

Daily account limits

A daily limit repeats until removed or until its optional end date. New daily limits start tomorrow or later, using earliest_daily_start_date from the list response. Edits use optimistic concurrency: you send expected_revision from the latest list response, and a stale revision returns 409.

curl -X POST "https://api.ads.openai.com/v1/ad_account/daily_spend_limit"   -H "Authorization: Bearer $OPENAI_ADS_API_KEY"   -H "Content-Type: application/json"   -d '{
    "amount_micros": 100000000,
    "expected_revision": 12,
    "start_date": "2026-10-01",
    "end_date": null
  }'

The example creates a 100 USD daily allowance with no end date. Increases and decreases take effect on save. Removal also takes effect on save and, per OpenAI, retains historical accounting for delayed charges.

Why Do Account Limits and Campaign Budgets Need Separate Checks?

Because they apply independently and neither allocates to the other. OpenAI states an account limit does not allocate a budget to each campaign, so a campaign can have budget remaining while the account's active limit is exhausted. Conversely, removing an account limit does not remove the campaigns' own budgets. Raising a campaign budget does not override an exhausted account limit.

For agency practice in 2026 this is the mechanism to use for client protection. Campaign budgets express the media plan; an account window tied to the insertion order expresses the contractual ceiling. If a script sets a campaign budget wrong, the account limit still holds. OpenAI also warns that if your integration uses another account spending control, inspect it separately rather than assuming that deleting a window removes every account-level control.

What Errors Should You Expect on Spending Limits?

OpenAI documents a specific error table for spending limit changes, and the 503 behaviour is the one worth building into tooling.

StatusWhat to do
400Correct missing or malformed fields, including invalid dates or dates outside 2000-01-01 to 2100-01-01
409Refresh the list and reconcile a stale revision or configuration conflict before resubmitting
422Correct the amount, date ordering, overlapping limits, or a change to a completed window. A decrease below recorded spend returns budget_window_amount_below_spend
503Refresh before retrying a daily mutation, because the change may have succeeded even if its response could not be loaded

That last row is the important one. A naive retry on 503 can apply a change twice, or reapply an old value over a newer one. Refresh, compare, then decide.

What Must an Agency Confirm Before Managing a Client Account?

OpenAI's API Partner Setup guide lists the prerequisites: an Ads API key for the client ad account, access to the client's website and brand assets, and a server-side secret manager for the Ads API key and any Conversions API keys you create. Each key works with one ad account, so per-client key management is the operating model.

Several capabilities must also be enabled for the specific client account, and the failure modes are distinctive enough to recognise. A brand update returning 403, or /conversions/pixels or /conversions/api_keys returning 404 with Not found, means contact your OpenAI partner representative. Conversion-optimised campaigns also need enabling; a 403 reading Conversion bidding is not enabled has the same remedy. A Client data source not found response means an event setting references a source that does not exist in the current ad account, which usually means a key for the wrong client. The measurement side is covered in the Measurement Pixel section, and conversion bidding in the oCPC section.

What Are the Common Account Mistakes?

What Campaign Objectives Does ChatGPT Ads Support in 2026?

Three objectives, set as bidding_type on the campaign: impressions, clicks and conversions. The objective determines what delivery optimises for. A separate setting on the ad group, billing_event_type, determines what you actually pay for. Those two are not the same field and not always the same thing, which is the single most useful mechanic to understand before you build anything.

ObjectiveBest forHow you payWhat delivery optimises for
impressions (CPM)Reach and awarenessPer 1,000 impressionsBroad delivery at scale
clicks (CPC)Engagement and trafficPer valid clickClicks from people likely to engage
conversions (oCPC)A tracked action after a clickPer valid click, not per conversionClicks more likely to lead to your selected conversion event

The third row is the unusual one. A conversions campaign optimises toward a conversion event but bills on valid clicks, so the bid you set is a CPA bid used as an optimisation input rather than a price you pay per conversion. We cover that billing shape separately in the conversion-optimised campaigns section.

How Do Bid Strategies Work in ChatGPT Ads in 2026?

Three strategies, set as bidding_config.strategy on the ad group. fixed_bid means you supply the bid. maximize_clicks and maximize_conversions let OpenAI adjust bids within your daily budget, and OpenAI brands those two jointly as Maximize Results. The documentation states both are available for standard and product-feed campaigns.

StrategyUse whenCompatible objectivesBudgetBid amount
fixed_bidYou want to set and adjust the bid yourselfImpressions, clicks, conversionsDaily or lifetimeProvide max_bid_micros
maximize_clicksYou want OpenAI to seek more clicks from your budgetClicksDaily onlyOmit max_bid_micros
maximize_conversionsYou want OpenAI to seek more conversions from your budgetConversionsDaily onlyOmit max_bid_micros

Only five combinations of objective, billing event and strategy are valid, and the documentation lists them explicitly. Memorise this table and most of your 400-level errors disappear.

Campaign bidding_typeAd group billing_event_typeAd group strategy
impressionsimpressionfixed_bid
clicksclickfixed_bid
clicksclickmaximize_clicks
conversionsclickfixed_bid
conversionsclickmaximize_conversions

The Maximize Results prerequisites people miss

Why Does Paying Per Click While Optimising to Conversions Matter?

Because the risk sits in a different place. On a pay-per-conversion model the platform carries some of the risk that clicks do not convert. On oCPC you carry it: if conversion rates fall, you still pay for every valid click. OpenAI is explicit that billing does not change to pay per conversion, that you are charged only when a valid click occurs, and that the auction determines the actual CPC.

The upside for an advertiser is transparency. You are paying for something you can see and audit in your own analytics, clicks, rather than for a conversion count that depends on the platform's attribution. The trade-off is that a broken tracking setup does not stop spend. It just makes optimisation worse while the clicks keep billing, which is why measurement has to be right before you launch.

The sentence to repeat to every client in 2026

OpenAI's guidance is to treat the CPA bid as an optimisation input, not as a conversion charge. Your cost per conversion is spend divided by conversions, and it can sit above or below the CPA bid you set, because the bid steers the auction rather than pricing the outcome.

What Does the CPA Bid Actually Control?

For an oCPC campaign, max_bid_micros on the ad group is the CPA bid, even though billing uses valid clicks. OpenAI's example: 100000000 is a 100.00 USD CPA bid in a USD account, using the standard micros scaling of 1,000,000 per major currency unit. The bid controls how the campaign competes for conversion-likely clicks.

OpenAI describes the mechanism in one sentence: oCPC uses your selected conversion event together with ad quality, relevance, click likelihood and conversion likelihood to favour clicks more likely to lead to that event. That is the decision the platform takes out of your hands. You choose the event and the CPA bid; the platform decides which clicks are worth competing for.

What Must Be True Before You Create an oCPC Campaign?

Four preconditions, and the first one is not something you can configure yourself. Skipping any of them produces either an error at creation or a campaign that optimises badly.

  1. The ad account must support conversion bidding. If campaign creation returns 403 with Conversion bidding is not enabled, OpenAI's instruction is to contact your OpenAI partner representative. This is an account-level gate.
  2. Conversion tracking must be set up with the JavaScript pixel, the Conversions API, or both. OpenAI states the Conversions API is a more reliable tracking source than the pixel alone.
  3. You need exactly one active standard conversion event to use as the optimisation goal. Custom events cannot be oCPC optimisation goals.
  4. The conversion event setting must belong to the current ad account and connect to one active conversion source.

The measurement layer behind points two to four is covered in the Measurement Pixel and Conversions API section. If that layer is not verified, do not launch oCPC, because a campaign optimising toward a misfiring event will keep paying for clicks while learning the wrong thing.

Which Conversion Events Can You Optimise Toward?

Standard events only, and exactly one per campaign. OpenAI's examples of an optimisation goal include order_created, lead_created and registration_completed. A custom event such as a quote request can be tracked and reported on, but cannot be the thing an oCPC campaign optimises toward.

Business goalStandard event to optimise toward
E-commerce purchaseorder_created
Lead form or contact requestlead_created
Account or event signupregistration_completed
Demo or consultation bookedappointment_scheduled
Paid subscription startedsubscription_created
Free trial startedtrial_started
Bespoke action, such as a quote requestNot eligible as an oCPC goal; track it as a custom event instead

The practical consequence for a B2B or services advertiser in 2026: if your real goal is a bespoke action, map it to the closest standard event in your tracking rather than sending it only as custom. Otherwise you can measure it but never optimise toward it.

How Do You Create a Conversion-Optimised Campaign?

Create the campaign paused with bidding_type: "conversions" and the event setting attached, then create ad groups with click billing and a CPA bid, then create ads, then activate once everything is ready. OpenAI's own example uses a lifetime budget:

curl -X POST "https://api.ads.openai.com/v1/campaigns"   -H "Authorization: Bearer $OPENAI_ADS_API_KEY"   -H "Content-Type: application/json"   -d '{
    "name": "Acme purchases",
    "status": "paused",
    "budget": { "lifetime_spend_limit_micros": 250000000 },
    "bidding_type": "conversions",
    "conversion_event_setting_ids": ["ces_123"]
  }'

Then the ad group, with billing_event_type set to click and the CPA bid in max_bid_micros:

curl -X POST "https://api.ads.openai.com/v1/ad_groups"   -H "Authorization: Bearer $OPENAI_ADS_API_KEY"   -H "Content-Type: application/json"   -d '{
    "campaign_id": "cmpn_101",
    "name": "US English",
    "status": "active",
    "bidding_config": {
      "billing_event_type": "click",
      "max_bid_micros": 100000000
    }
  }'

Note one compatibility point from the Ads API guide. A fixed CPA bid works with either a daily or lifetime budget. If you want OpenAI to manage bids instead, using maximize_conversions, the campaign needs a daily budget, the ad group must omit max_bid_micros, and an Idempotency-Key is required when creating that ad group.

How Does oCPC Work for Product-Feed Campaigns?

The same way, using the same endpoint, and it is also in open beta. You add mode: "product_feed" and the ID of a product feed linked to the ad account alongside the conversion bidding fields. The child ad group automatically inherits the campaign's feed; you include product_set only to specify product filters, and its product_feed_id must match the campaign's feed.

curl -X POST "https://api.ads.openai.com/v1/campaigns"   -H "Authorization: Bearer $OPENAI_ADS_API_KEY"   -H "Content-Type: application/json"   -d '{
    "name": "Running shoes catalog purchases",
    "status": "paused",
    "mode": "product_feed",
    "product_feed_id": "product_feed_123",
    "budget": { "lifetime_spend_limit_micros": 250000000 },
    "bidding_type": "conversions",
    "conversion_event_setting_ids": ["ces_123"]
  }'

Remember the targeting constraint from the targeting section: new product-feed campaigns support geographic targeting and exclusions only at country level.

What Cannot Be Changed Once an oCPC Campaign Exists?

Two things, and both force a new campaign. OpenAI answers these directly in its common questions, and they shape how you name and plan campaigns from the start.

Change you might wantAllowed?What to do
Convert an existing CPM or CPC campaign to oCPCNoCreate a new campaign with bidding_type: "conversions"
Change the selected conversion eventNoCreate a new campaign optimising toward the new event
Change the campaign goalNoCreate a new campaign
Switch between a fixed CPA bid and Maximize conversionsYes, within the same objectiveUpdate the ad group's bidding_config, respecting budget rules
Adjust the CPA bid amountYesUpdate max_bid_micros on the ad group

The planning lesson: a traffic campaign that starts converting well cannot be promoted to oCPC in place. You rebuild it. Teams that expect to graduate from CPC testing to conversion bidding should name and structure the CPC campaign so its learnings transfer cleanly to the oCPC campaign that replaces it.

How Should You Judge oCPC Performance?

On conversions first, and on enough volume to mean something. OpenAI's guidance is to review impressions, clicks, conversions, spend, click-through rate and average CPC together in Ads Manager, and notes that because oCPC optimises toward the selected event, conversions are the primary outcome to review. Calculate cost per conversion yourself as spend divided by conversions.

OpenAI's own improvement list is short and worth following literally:

Two reporting cautions carry over from the platform's general behaviour. Conversions update through daily processing, so allow at least a day before drawing conclusions. And view-through conversions are reported separately and do not feed bidding, billing or CPA, which all remain click-through-based. Judge an oCPC campaign on click-through conversions.

The volume question nobody likes to answer

OpenAI's advice to use an event with enough volume is the most important line on the page for smaller advertisers. If your purchase volume is low, optimising toward order_created gives the system very little signal. A higher-funnel standard event such as checkout_started or items_added produces more signal at the cost of optimising toward something further from revenue. Which trade-off is right depends on your volume, and that is a decision to make deliberately rather than by defaulting to the purchase event.

What Are the Common oCPC Mistakes?

How Do Budgets and Micros Work in 2026?

Budgets sit on the campaign and are expressed in micros, where one million micros equals one major unit of the account currency. You provide exactly one budget field: either daily_spend_limit_micros or lifetime_spend_limit_micros. A campaign cannot have both. Daily minimums depend on the account currency, and a request below the minimum returns an error stating the required amount.

Amount in a USD accountValue to send
1.00 USD1000000
2.50 USD2500000
50.00 USD50000000
500.00 USD lifetime500000000

Two behaviours matter operationally. A budget update sets the new amount rather than adding to the old one, so sending 75000000 makes the daily budget 75 USD and does not add 75 USD. And you cannot reduce a lifetime budget below what the campaign has already spent.

The budget switch that only works one way

You can switch a lifetime-budget campaign to a daily budget through a campaign update. You cannot switch a daily budget back to lifetime; OpenAI's documentation says to create a new campaign if you need a lifetime budget instead. That matters because Maximize Results requires a daily budget, so moving a lifetime campaign onto automated bidding is a one-way door for that campaign.

How Do You Set a Bid Correctly, Including CPM?

max_bid_micros uses the same micros scaling as budgets, so a 2.50 USD click bid is 2500000. Impression bidding is where teams get this wrong. The API expects a bid per impression, not per thousand impressions. OpenAI's own worked example: a 60 USD CPM is 0.06 USD per impression, so you send 60000 micros, calculated as 60 divided by 1,000 multiplied by 1,000,000.

Getting this backwards by a factor of 1,000 in either direction is the most expensive arithmetic error available on this platform in 2026, so it is worth a second pair of eyes on the first impressions campaign you build.

The default that protects you in 2026

OpenAI's documentation states that new resources are created paused so you can finish setup before enabling delivery. Nothing you create through the API starts spending on its own. Activation is a separate, explicit call on each level, and you activate from the bottom up: the ad, then the ad group, then the campaign.

How Do You Launch a First Campaign Through the API in 2026?

Five creates and three activations. The sequence below follows OpenAI's own quickstart: a paused clicks campaign with a fixed bid, then an ad group, then an uploaded image, then a chat-card ad, then preview and activate. Budget and bid values in the documentation are illustrative USD amounts.

1. Create the campaign

curl -X POST "https://api.ads.openai.com/v1/campaigns"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -H "Idempotency-Key: first-campaign-001"   -H "Content-Type: application/json"   -d '{
    "name": "Spring launch",
    "status": "paused",
    "bidding_type": "clicks",
    "budget": { "daily_spend_limit_micros": 50000000 },
    "targeting": { "locations": { "countries": ["US"] } }
  }'

2. Create the ad group with a bid and context hints

curl -X POST "https://api.ads.openai.com/v1/ad_groups"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -H "Idempotency-Key: first-ad-group-001"   -H "Content-Type: application/json"   -d '{
    "campaign_id": "cmpn_123",
    "name": "Trail running",
    "status": "paused",
    "context_hints": ["Trail running shoes for rocky terrain"],
    "bidding_config": {
      "billing_event_type": "click",
      "strategy": "fixed_bid",
      "max_bid_micros": 2000000
    }
  }'

3. Upload the creative image

curl -X POST "https://api.ads.openai.com/v1/upload"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -F "file=@/path/to/product-image.png"

Use JPEG, PNG or WebP at a minimum of 640 by 640 pixels, and save the returned file_id.

4. Create the ad

curl -X POST "https://api.ads.openai.com/v1/ads"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -H "Idempotency-Key: first-ad-001"   -H "Content-Type: application/json"   -d '{
    "ad_group_id": "adgrp_123",
    "name": "Trail shoe launch",
    "status": "paused",
    "creative": {
      "type": "chat_card",
      "title": "Find your next trail shoe",
      "body": "Explore shoes made for your next outdoor run.",
      "target_url": "https://example.com/trail-shoes",
      "file_id": "file_123"
    }
  }'

Creating an ad submits its creative for review. Titles run 3 to 50 characters, bodies up to 100 characters, and the destination must be an HTTP or HTTPS URL no longer than 2,048 characters that is accessible to OpenAI's ad crawlers.

5. Preview, inspect, then activate bottom-up

curl -X POST "https://api.ads.openai.com/v1/ads/ad_123/preview"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"

curl -X POST "https://api.ads.openai.com/v1/ads/ad_123/activate"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"
curl -X POST "https://api.ads.openai.com/v1/ad_groups/adgrp_123/activate"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"
curl -X POST "https://api.ads.openai.com/v1/campaigns/cmpn_123/activate"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"

OpenAI is explicit that a preview shows appearance and does not confirm serving eligibility, and that activation enables delivery only when the remaining requirements are satisfied.

What Cannot You Change After Creation in 2026?

More than on most ad platforms, and this is the section worth reading before you build a naming convention. OpenAI documents several settings as fixed at creation, which means your structure has to anticipate them rather than correct them later.

SettingChangeable?What to do instead
Campaign objective (bidding_type)NoCreate a new campaign.
Selected conversion event on an oCPC campaignNoCreate a new campaign.
Daily budget back to lifetimeNoCreate a new campaign.
Moving an ad to a different ad groupNoCreate the ad in the target ad group.
Account currency and timezoneNoSet correctly at account creation.
Bid strategy within the same objectiveYesUpdate bidding_config, respecting the budget rules.
CreativeYesUpdating it creates a new submitted version and starts another review.

How Do You Diagnose a Campaign That Is Not Delivering?

Two include parameters do most of the work. Request bid_too_low and serving_issues on the ad group, and serving_issues on the campaign. OpenAI is careful about what the first one means: bid_too_low: true indicates the bid may be too low for reliable delivery, and it is guidance rather than a serving restriction.

curl -G "https://api.ads.openai.com/v1/ad_groups/adgrp_123"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   --data-urlencode 'include[]=bid_too_low'   --data-urlencode 'include[]=serving_issues'

Work through the layers in order, because each one can independently stop delivery: account status and account reviews, the account spend limit, the campaign budget and schedule, campaign targeting, the ad group bid, ad review status, and for product-feed campaigns whether any products match your filters. OpenAI states plainly that campaign budgets and account spend limits apply independently, so raising a campaign budget does not override an exhausted account limit. The account management section covers that layer.

What Are the Rate Limits and Account Limits in 2026?

The Advertiser API enforces limits by both ad account and IP address, and a request has to stay within both. Bulk job creation has its own separate limit, covered in the Bulk API section.

LimitValue
Per endpoint600 requests per minute
Overall1,200 requests per minute
Bulk job creation10 requests per 10 seconds per ad account
Self-serve campaigns per ad account5,000 non-archived
Self-serve ad groups per ad account5,000 non-archived
Self-serve ads per ad account5,000 active or paused
Location IDs per campaign2,500
Context hints per ad group2,000

How Do You Add Tracking Parameters to ChatGPT Ads?

Through landing_page_configuration.query_string_template, which can be set at campaign, ad group or ad level. The template supports macros, and the one that matters for stitching platform data to your own analytics is {oppref}, the click identifier.

{
  "landing_page_configuration": {
    "query_string_template": "utm_source=openai&utm_campaign={campaign_id}&utm_content={ad_id}&click_id={oppref}"
  }
}

Capture oppref on your landing page and pass it back on server-side conversions, because the Conversions API does not capture it automatically. That mechanic is the backbone of attribution on this platform and is covered in the Measurement Pixel and Conversions API section.

How Should You Read ChatGPT Ads Reporting in 2026?

Through the Insights endpoints, and with patience about which numbers have settled. OpenAI documents three different processing speeds, and conflating them produces the classic false alarm on day one of a campaign.

MetricsFreshnessReporting history available
Impressions, clicks, CTRCan appear within minutes; recent values may changeHourly: about 30 days
Spend, CPC, CPMReflect finalised activity and can update laterNon-hourly, excluding product: most recent 365 days
Conversions and purchase outcomesDaily processing; allow at least one day to appearProduct reporting: about 30 days

Two reading notes from the documentation. CTR is returned as a ratio, so 0.04 means 4 percent. And a null metric means unavailable or not calculable, not zero, which matters for ROAS when purchase value is missing or spend is zero. Because recent clicks can arrive before finalised spend, dividing the latest spend by the latest clicks can disagree with the returned CPC.

What Has Changed in the ChatGPT Ads API During 2026?

OpenAI publishes a changelog, and the cadence tells you how young this platform is. The initial version was published as v1, and the documented 2026 additions run through the year.

Practical consequence for an agency in 2026: pin nothing to a capability you have not re-checked this quarter, and read the changelog before you conclude a feature does not exist.

What Targeting Does ChatGPT Ads Offer?

Four primitives, and they do not all live at the same level. Geographic targeting, platform targeting, and audience inclusion and exclusion are all campaign-level settings. Context hints sit on the ad group. OpenAI states that these settings work together and that matching one does not override the others, so a user has to satisfy every configured dimension to be eligible.

The fourth primitive, context hints, has no direct equivalent on Meta or Google. It is how you describe what an ad is about so the platform can judge relevance to a conversation, and understanding what it is not is as important as understanding what it is. The Ads API guide covers structure and bidding; this one covers who sees the ad.

PrimitiveLevelFieldWhat it does
GeographicCampaigntargeting.locations, targeting.excluded_locationsCountry codes or location IDs, with exclusions
PlatformCampaigntargeting.platforms.includedWhich ChatGPT surfaces can deliver
Custom audiencesCampaigntargeting.custom_audiences, targeting.excluded_custom_audiencesFirst-party lists for inclusion or exclusion
Context hintsAd groupcontext_hintsDescribes the offering so the platform can judge relevance
Audience bid multipliersAd groupbidding_config.custom_audience_bid_multipliersAdjusts a fixed bid for members, without restricting eligibility

Why Does Everything Being Campaign-Level Change Your Account Structure?

Because on Meta or Google you would express several targeting variations as several ad sets under one budget. Here, targeting changes mean new campaigns, and each campaign carries its own budget. A media buyer planning three geographies and two audience splits is planning six campaigns and six budgets, not one campaign with six children.

That has a practical consequence for testing. Budget fragmentation is real: six campaigns each learning separately will take longer to produce readable results than one campaign would. In 2026 the sensible approach on a new channel is to start with the smallest number of campaigns that still answers one clear question, then split once something works.

How Do You Set Geographic Targeting?

Two ways: ISO 3166-1 alpha-2 country codes, or location IDs returned by the geo lookup endpoint. Country codes are simple; location IDs let you reach regions and markets. OpenAI warns that a code's ISO validity does not mean it is available for advertising in your account, so use supported advertising locations rather than assuming.

curl -G "https://api.ads.openai.com/v1/geo_lookup/search"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   --data-urlencode 'q=San Francisco'   --data-urlencode 'limit=5'

The response returns the location id, display name, canonical_name, country_code, type, parent_id and parent_country, plus region_code where available. The ID identifies the target; the names are there to help you pick the right result. OpenAI also publishes the full catalogue as a downloadable CSV, which is the practical way to build a mapping table once rather than querying repeatedly.

Targeting a country while excluding a region

curl -X POST "https://api.ads.openai.com/v1/campaigns/cmpn_123"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -H "Content-Type: application/json"   -d '{
    "targeting": {
      "locations": { "countries": ["US"] },
      "excluded_locations": { "include": [ { "id": "2000043" } ] }
    }
  }'

You can include up to 2,500 IDs in geographic inclusion and exclusion lists. If you provide no location targeting at all, the campaign can target all available locations, which is rarely what anyone intends on a first test.

The product-feed limitation to check before you plan in 2026

OpenAI documents that new product-feed campaigns support geographic targeting and exclusions only at country level. If your retail plan assumed city or region targeting on a catalogue campaign, that assumption needs revisiting before the media plan is signed off.

Which Platforms Can You Target, and What Does web Actually Mean?

Six values, and one of them is routinely misread. The broad groups are ios_app, android_app and web. A changelog entry dated 10 September 2026 added granular web values: desktop_web, ios_web and android_web. The existing web value continues to include all web platforms, so existing campaigns using it do not need to change.

API valuePlatformIncludes
ios_appiOS appThe native ChatGPT app on iOS
android_appAndroid appThe native ChatGPT app on Android
desktop_webDesktop webChatGPT in a desktop web browser
ios_webiOS webChatGPT in a web browser on iOS
android_webAndroid webChatGPT in a web browser on Android
webWebAll web platforms, including mobile browsers

The misreading OpenAI explicitly corrects: selecting web does not mean desktop-only traffic. An iPhone user visiting ChatGPT in a browser belongs to web inventory rather than the iOS app group. If you want desktop only, use desktop_web without web. And at creation, omitting platform targeting defaults to all platforms.

How Do Custom Audiences Work in ChatGPT Ads?

You upload first-party identifiers, OpenAI matches them to users, and the resulting audience can be included, excluded or used to adjust a fixed bid. Uploads support email, phone, their supported SHA-256 variants, and GAID identifiers. OpenAI tells you to use the audience-specific normalisation rules before hashing and not to assume another API uses the same phone format, which is a genuine trap for teams reusing a Meta or Google pipeline.

curl -X POST "https://api.ads.openai.com/v1/uploads"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -F "file=@/path/to/audience.csv;type=text/csv"   -F "purpose=custom_audience"
curl -X POST "https://api.ads.openai.com/v1/custom_audiences"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -H "Content-Type: application/json"   -d '{
    "name": "High-value customers",
    "file_id": "oaisdmntci_123",
    "identifier_resolution": "auto",
    "filename": "audience.csv",
    "mimetype": "text/csv",
    "file_size": 123456
  }'

Files are UTF-8 CSV or TXT up to 500 MB, with identifier_resolution: "auto" processing supported columns in a CSV. For a single-type TXT file, provide identifier_type with one identifier per line. Everything is asynchronous, so you wait for status: "ready" before using the audience.

The size thresholds that decide what an audience can do

This is the most commercially important table on the page, because it determines whether your CRM list is usable at all. Eligibility is per intended use and is separate from the audience being ready.

Intended useSize requirementWhat it means in practice
exclusionReady small or empty audiences can be used, with no minimum matched sizeSuppression works at any list size, including an empty list you add to later
inclusionMust meet the matched-user minimumTargeting your customer list needs scale
bid_multiplierMust meet the matched-user minimumBid adjustments need the same scale as inclusion

OpenAI gives 25,000 matched users as the public planning threshold for inclusion and bid adjustments, and is careful about what that means: privacy safeguards can affect the exact boundary, and uploading 25,000 identifiers does not guarantee enough matched users. Uploaded row counts do not equal matched-user counts. For most mid-market advertisers in 2026, that makes suppression the realistic first use of custom audiences and inclusion a later one.

You can check eligibility directly rather than guessing:

curl -G "https://api.ads.openai.com/v1/custom_audiences"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   --data-urlencode "intended_use=exclusion"   --data-urlencode "custom_audience_ids[]=caud_123"

Maintaining an audience without breaking your campaigns

Add, remove and replace operations update membership while keeping the audience ID, so the campaigns and ad groups referencing it keep working. Each returns an operation rather than the updated audience, and you poll the returned operation_id for completion.

ActionEndpointInput
Add members, keeping existing onesPOST /v1/custom_audiences/{id}/addInline identifiers or an uploaded file
Remove selected membersPOST /v1/custom_audiences/{id}/removeInline identifiers or an uploaded file
Replace the complete listPOST /v1/custom_audiences/{id}/replaceAn uploaded file
Merge existing audiencesMerge operation2 to 64 existing audience IDs, producing a new union audience

Inline request bodies must not exceed 16 MiB, and each new add, remove, replace or merge needs a new Idempotency-Key, reusing the original key only when retrying the same submission.

What Is the Difference Between Inclusion and a Bid Multiplier?

Inclusion restricts eligibility to matching users. A bid multiplier adjusts a fixed bid for matching users while leaving everyone else eligible under the campaign's targeting. OpenAI states plainly that bid multipliers do not change which users are eligible to see a campaign.

For a media buyer that distinction is the difference between a prospecting campaign that quietly stopped reaching new people and one that simply pays more for known customers. Two constraints go with it: multipliers work only with fixed_bid, not with Maximize Results, and small exclusion audiences are not automatically eligible for bid adjustments.

How Do Inclusion and Exclusion Interact?

Exclusions win. OpenAI documents that you may configure both inclusion and exclusion targeting on the same campaign, that exclusions take precedence when someone belongs to both, and that the same audience ID cannot appear in both lists in one campaign. If you combine inclusion and exclusion, the remaining eligible audience must still meet the inclusion minimum, which is an easy way to accidentally make a campaign undeliverable.

curl -X POST "https://api.ads.openai.com/v1/campaigns/cmpn_123"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -H "Content-Type: application/json"   -d '{
    "targeting": {
      "locations": { "countries": ["US"] },
      "custom_audiences": { "ids": ["caud_123"] },
      "excluded_custom_audiences": { "ids": ["caud_456"] }
    }
  }'

Why Must You Read a Campaign Before Changing Its Targeting?

Because a partial update can erase targeting you meant to keep. OpenAI's warning is specific: geographic and audience updates can replace existing targeting criteria, so you should retrieve the campaign first and send the complete intended configuration for those objects. The API does handle a platform-only update separately from geographic and audience changes, but if you send geographic or audience fields you must build the full object.

This is the single most dangerous operational behaviour on the platform for an agency. A script that nudges one country onto a campaign can silently drop an exclusion list that was protecting a client from advertising to existing customers. Build read-modify-write into your tooling from the start, and retrieve the campaign afterwards to confirm what saved.

What Are Context Hints, and How Should You Write Them?

Context hints are ad-group-level text that describes relevant products, use cases or needs the creative and landing page may not fully cover. OpenAI is explicit about two things they are not: they are not exact-match keywords, and they do not replace explicit geographic, platform or audience targeting. An ad group can hold up to 2,000 hints.

Less usefulMore useful
ShoesLightweight trail running shoes for rocky terrain
OutdoorsWater-resistant footwear for wet-weather hiking
California customersUse geographic targeting for California; describe the product's use case in hints

OpenAI notes these examples illustrate writing style rather than guaranteeing that a particular conversation will trigger an ad. The mental model that fits the documentation is a short, plain-language product description written for a reader who has never seen your brand, not a keyword list. The third row is the instructive one: geography belongs in targeting, not in a hint.

curl -X POST "https://api.ads.openai.com/v1/ad_groups/adgrp_123"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -H "Content-Type: application/json"   -d '{
    "context_hints": [
      "Lightweight trail running shoes for rocky terrain",
      "Water-resistant footwear for wet-weather hiking"
    ]
  }'

Updating context_hints replaces the current list. To add one hint you retrieve the ad group, append to the existing list and submit the complete intended list. An empty array clears the list, and omitting the field leaves it unchanged.

What Are the Compliance Limits on Audiences?

Two that matter commercially. First, custom audiences are not supported for campaigns targeting the European Economic Area or Switzerland, where OpenAI states personalised ads are not yet available. If you run European media, audience-based targeting is simply not part of the plan there.

Second, OpenAI sets a clear data-sourcing rule: upload only first-party audience data you have the right to use for ads, and do not upload broker-sourced data. Before uploading, confirm your use complies with required rights, notices, consents, permissions and legal bases and the Ad Tools Terms, and obtain privacy or legal approval. For teams operating under the DPDP Act in India or GDPR in Europe, that is a step with a named owner, not a checkbox. This is a summary of OpenAI's published platform terms rather than legal advice; confirm your own obligations with counsel.

What Are the Common Targeting Mistakes?

What Is the ChatGPT Measurement Pixel?

The Measurement Pixel is OpenAI's browser SDK for measuring website events that can be attributed to ads in ChatGPT. You add a script to your site, initialise it with a Pixel ID, and call oaiq("measure", ...) when a conversion happens. Alongside it, the Conversions API sends the same kinds of events from your server. Both identify the same data source through a Pixel ID.

If you are evaluating ChatGPT Ads as a channel, this is the part to build first. Without it you can report clicks and spend but not outcomes, and you cannot use conversion-optimised bidding at all. The Ads API guide covers campaign mechanics; this one covers the measurement layer underneath.

How Do the Three Building Blocks Fit Together?

Three distinct objects, and conflating them is the most common setup error. A data source receives events from your website or server. A conversion event setting defines which event from that source counts as a conversion. A campaign then uses the attached event setting for reporting and, when configured, for optimisation. Sending an event and creating a setting are separate steps: a setting selects an event from a source, it does not send events itself.

ObjectWhat it doesCreated by
Data source (pixel)Receives events from browser or serverPOST /v1/conversions/pixels
Conversion event settingDefines which event counts as a conversion, with an attribution windowPOST /v1/conversions/event_settings
Campaign attachmentConnects the setting to a campaign for reporting or optimisationconversion_event_setting_ids on the campaign

One detail catches nearly everyone: a data source returns two identifiers with different jobs. The pixel_id initialises the Pixel, sends server events and checks recent events. The id selects the source when creating a conversion event setting. OpenAI's documentation is explicit that you use the source's id in source_ids, not its pixel_id.

Why Would You Use the Conversions API as Well as the Pixel?

Because a server records things a browser cannot see, and because OpenAI states directly that the Conversions API is a more reliable tracking source than the pixel alone. The browser pixel measures what happens on the page. The server integration reports confirmed outcomes such as a completed order that survived payment capture. Running both, with shared event IDs so duplicates are recognised, is the configuration that reports the truth.

IntegrationWhere events are sentWhen to use it
Measurement PixelThe customer's browserMeasure actions that happen on your website
Conversions APIYour serverSend actions recorded by your server, such as confirmed orders
BothBrowser and serverMeasure the same actions through both, with shared event IDs to prevent duplicates

A server-only integration still needs a Pixel ID, but does not require installing the browser pixel. That is useful for teams whose consent posture or site architecture makes a client-side tag awkward.

How Do You Install the Measurement Pixel?

One script in the <head> of every page where you want to capture conversions. OpenAI advises putting it near the top of the head so early conversions are not lost while other content loads. pixelId is required; debug is optional and logs SDK activity to the browser console while you test.

<script>
  (function (w, d, s, u) {
    if (w.oaiq) return;
    var q = function () { q.q.push(arguments); };
    q.q = [];
    w.oaiq = q;
    var js = d.createElement(s);
    js.async = true;
    js.src = u;
    var f = d.getElementsByTagName(s)[0];
    f.parentNode.insertBefore(js, f);
  })(window, document, "script", "https://bzrcdn.openai.com/sdk/oaiq.min.js");
  oaiq("init", { pixelId: "<YOUR-PIXEL-ID>" });
</script>

Then fire an event when the action completes

oaiq(
  "measure",
  "order_created",
  { type: "contents", amount: 8900, currency: "USD" },
  { event_id: "order_12345" }
);

Amounts use the currency's standard minor unit, so 8900 is 89.00 USD. Use the real order ID as the event ID, and keep it identical if you also send the same purchase from your server.

What Does the Content Security Policy Need to Allow?

Four entries, and this is the step that silently breaks installs on sites with a strict CSP. If your site enforces one, merge these sources into the existing policy rather than discovering later that events never left the browser.

DirectiveSourcePurpose
script-srchttps://bzrcdn.openai.comLoad the Measurement Pixel SDK
connect-srchttps://bzr.openai.comSend events with fetch or sendBeacon
connect-srchttps://bzrcdn.openai.comFetch per-pixel configuration
img-srchttps://bzr.openai.comSend events with the image request fallback

How Do You Handle Consent?

Set consent before initialising the pixel. OpenAI documents that the pixel initialises consent to true by default unless you set it to false or the pixel finds a stored denial. When consent is false the pixel does not send measurement-event pings, and setting it back to true allows future events but does not replay blocked ones.

oaiq("consent", false);
oaiq("init", { pixelId: "<YOUR-PIXEL-ID>" });

// Call this after the user grants measurement consent.
oaiq("consent", true);

Two consequences worth stating to a client. Blocked events are gone, not queued, so a slow consent banner costs you measurable conversions. And calling oaiq("consent", false) removes the pixel's cookies. For any team operating under the DPDP Act in India or GDPR in Europe, the default-true behaviour is the setting your privacy review will ask about, so configure it deliberately rather than inheriting it.

What Cookies Does the Pixel Set, and for How Long?

Two first-party cookies when measurement consent is granted, with different lifetimes and different refresh behaviour. OpenAI notes these are the lifetimes requested by the pixel, and that browser restrictions or cleared cookies can shorten them.

CookieExpiryWhat it stores and how it refreshes
__oppref30 days after the pixel writes itThe oppref attribution identifier from the landing page URL. Each time the pixel captures a non-empty oppref parameter, including the same value again, the expiry resets to 30 days. Reading the stored cookie on a visit without the parameter does not extend it.
__obref365 days after creationA randomly generated browser reference for your website. A valid stored reference is reused without extending expiry.

OpenAI is careful to separate these from attribution: cookie expiry is browser storage only and is distinct from conversion attribution windows and conversion-data retention.

How Do You Send Server-Side Conversions?

Create a Conversions API key with your Advertiser API key, then post events to a different host. Setup and management requests go to api.ads.openai.com with the Advertiser key; event requests go to bzr.openai.com with the Conversions key. Keep both on your server.

curl -X POST "https://api.ads.openai.com/v1/conversions/api_keys"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -H "Content-Type: application/json"   -d '{ "name": "Acme server events" }'
curl -X POST "https://bzr.openai.com/v1/events?pid=${PIXEL_ID}"   -H "Authorization: Bearer ${OPENAI_CONVERSIONS_API_KEY}"   -H "Content-Type: application/json"   -d '{
    "events": [
      {
        "id": "order_12345",
        "type": "order_created",
        "timestamp_ms": 1784304000000,
        "action_source": "web",
        "source_url": "https://shop.example.com/checkout/confirmation",
        "data": { "type": "contents", "amount": 8900, "currency": "USD" }
      }
    ]
  }'

Two testing affordances are genuinely useful. Adding "validate_only": true at the top level validates a request without saving events, and those requests do not appear in event monitoring. And the recent-events endpoint returns a sample from roughly the last 15 minutes, which is how you confirm an integration before you trust a report.

The identifier the Conversions API will not capture for you

When an ad click supplies an oppref identifier, you must capture it and include the original value as oppref on the server event. OpenAI states the Conversions API does not capture this value automatically. Practically, that means your landing page needs to read the parameter and persist it into your order record, which is a development task somebody has to own before launch rather than after.

How Does Deduplication Work Between Browser and Server?

Through three shared values. For the same purchase sent through both integrations, use the same Pixel ID, the same event name such as order_created, and the same event ID, which is event_id on the pixel and id on the Conversions API. For custom events, also use the same custom_event_name. Those shared values let OpenAI recognise the duplicate so the action is not counted twice.

The one-line rule for 2026

Use your real order or lead identifier as the event ID everywhere. Teams that generate a fresh random ID per integration get double-counted conversions, and double-counted conversions feed conversion-optimised bidding, so the error does not stay a reporting problem for long.

Which Conversion Events Can You Send?

Thirteen event names, each with a defined data type. Standard events cover most commerce and lead flows, and custom exists for anything the taxonomy does not describe. Monetary values are integers in the ISO 4217 minor unit for the currency you send, so 129.99 USD is 12999.

Event nameData typeUse for
order_createdcontentsA purchase is completed
checkout_startedcontentsA user starts checkout
items_addedcontentsItems added to a cart, bundle or selection
contents_viewedcontentsA product, listing or article is viewed
page_viewedcontentsAn important page loads
lead_createdcustomer_actionA lead form is submitted or contact requested
registration_completedcustomer_actionAccount or event registration finishes
appointment_scheduledcustomer_actionA meeting, demo or consultation is booked
subscription_createdplan_enrollmentA paid subscription starts
trial_startedplan_enrollmentA free trial starts
app_installedcustomer_actionAn app install. Conversions API only, with action_source: mobile_app
app_openedcustomer_actionAn app open. Conversions API only
customcustomAnything outside the standard taxonomy

Two boundaries to respect. app_installed and app_opened are not supported by the JavaScript pixel and must go through the Conversions API. And OpenAI distinguishes page_viewed for page loads from contents_viewed for viewing a specific product or content item, including interactions after the page has loaded.

How Do You Create a Conversion Event Setting?

Name it, pick the event type, set an attribution window in days, and point it at one source. OpenAI's example uses a 30-day click attribution window, described as the time after an eligible ad click during which a conversion can be credited to it.

curl -X POST "https://api.ads.openai.com/v1/conversions/event_settings"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   -H "Content-Type: application/json"   -d '{
    "name": "Acme purchases",
    "event_type": "order_created",
    "attribution_window_days": 30,
    "source_ids": ["cds_123"]
  }'

For a custom event, send event_type: "custom" plus a custom_event_name that matches exactly what your integration sends. Keep that name consistent across the event and the setting or the setting will never match anything.

How Do Conversions Attach to Campaigns, and What Is a View-Through?

Attach settings through conversion_event_setting_ids on the campaign. Clicks and impressions campaigns can track conversions without changing their objective, which means you can measure outcomes on a traffic campaign without committing to conversion bidding. Updating the field replaces the list, so include every setting you want to keep.

On attribution, the documentation draws a line worth quoting to anyone reading a dashboard. The same events support click-through attribution and, where available for your account, view-through attribution. View-through conversions use a fixed one-day window after an eligible ad impression, require no integration changes, and are reported as a separate campaign-level metric in Ads Manager. They are not included in Conversions, which remains the click-through total. CPA, post-click conversion rate, bidding, billing and conversion optimisation all remain click-through-based. Where a conversion is eligible for both, the click takes precedence.

How Do You Verify the Integration Before Trusting a Report?

Check recent events on the source, then confirm the channel each event arrived through. The monitoring endpoint returns a sample of events from roughly the last 15 minutes, which is a testing and troubleshooting tool rather than a reporting one.

curl -G "https://api.ads.openai.com/v1/conversions/events"   -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}"   --data-urlencode "pid=${PIXEL_ID}"   --data-urlencode "limit=50"

Browser events show as pixel_sdk and server events as server_to_server, so you can prove both legs of a dual integration are live. For attributed conversion reporting and history, use Insights instead, and remember from the Ads API guide that conversions update through daily processing, so allow at least a day before drawing conclusions.

What Is Automatic Advanced Matching?

A pixel feature that improves measurement when a click identifier is unavailable. When enabled, the pixel automatically detects supported customer information on your website, then normalises and hashes it in the browser using SHA-256 before including it with conversion events. OpenAI states that raw customer information is not sent through automatic advanced matching, and that you do not need to pass customer information manually or change your implementation.

For agencies, the useful framing for a client conversation is that hashing happens client-side before transmission. That is still a processing activity you should be able to describe in a privacy notice, so document it rather than leaving it implicit.

What Are the Common Mistakes?

What Is the ChatGPT Ads Bulk API?

The Bulk API creates or updates campaigns, ad groups and ads in a single asynchronous job. You submit up to 1,000 operations, poll the job, and inspect the result of each operation. It is the tool an agency reaches for when a launch involves dozens of campaigns, or a weekly change touches hundreds of ad groups, and making one request per object would be slow and fragile.

One status line governs everything below. OpenAI states the Bulk API is in limited preview and is enabled per ad account. It is not included in the downloadable OpenAPI spec, and if a bulk endpoint returns 404, OpenAI's instruction is to contact your OpenAI account team to confirm access for the account associated with your Ads API key. Plan around that gate before you build tooling that depends on it.

Access check before anything else in 2026

Because access is enabled per ad account, an agency can find bulk working on one client account and returning 404 on the next. Confirm access for every client account you intend to manage this way before committing to a bulk-based workflow, and keep a non-bulk fallback using the standard endpoints covered in the Ads API guide.

Why Would an Agency Use the Bulk API Instead of Single Requests?

Because a launch built from single requests is a sequence of dependencies, and every dependency is a place for a script to fail halfway. You create a campaign, wait for its ID, create an ad group using that ID, wait, create an ad. Bulk collapses that into one submission where operations can refer to parents created in the same job, and returns a per-operation result you can audit.

How Do You Submit a Bulk Job?

One POST to /bulk_mutation_jobs containing an operations array. OpenAI's own example creates a campaign, an ad group and an ad in one request, all paused so they can be verified before delivery starts.

curl -X POST "https://api.ads.openai.com/v1/bulk_mutation_jobs"   -H "Authorization: Bearer $OPENAI_ADS_API_KEY"   -H "Content-Type: application/json"   -H "Idempotency-Key: spring-launch-job-001"   -d '{
    "validate_only": false,
    "partial_failure": true,
    "operations": [
      {
        "operation_id": "create-campaign",
        "type": "campaign.create",
        "idempotency_key": "campaign-spring-launch",
        "input": {
          "name": "Spring launch",
          "max_budget_micros": 100000000,
          "billing_event_type": "impression",
          "budget_type": "lifetime",
          "status": "paused"
        }
      },
      {
        "operation_id": "create-ad-group",
        "type": "ad_group.create",
        "idempotency_key": "ad-group-prospecting",
        "input": {
          "campaign_idempotency_key": "campaign-spring-launch",
          "name": "Prospecting",
          "context_hints": ["shoes", "spring fashion"],
          "status": "paused"
        }
      },
      {
        "operation_id": "create-ad",
        "type": "ad.create",
        "idempotency_key": "ad-prospecting-1",
        "input": {
          "campaign_idempotency_key": "campaign-spring-launch",
          "ad_group_idempotency_key": "ad-group-prospecting",
          "title": "Fresh shoes",
          "body": "Find your next pair",
          "target_url": "https://example.com/shoes",
          "source_image_url": "https://developers.openai.com/showcase/openai-imagegen-demo.png",
          "status": "paused"
        }
      }
    ]
  }'

The API returns 202 Accepted with a job ID and a status of pending. Notice two differences from the standard endpoints that will trip up anyone porting existing code: the bulk campaign input uses max_budget_micros with a budget_type field rather than the separate daily and lifetime budget fields, and the ad input takes a source_image_url rather than an uploaded file ID.

The three request-level fields

FieldRequiredWhat it does
operationsYesBetween 1 and 1,000 create or update operations
validate_onlyNoValidates fields and dependencies without changing resources. Defaults to false
partial_failureNoContinues independent operations after an error. Defaults to true

What Do partial_failure and validate_only Actually Guarantee?

Less than their names suggest, and this is the section to read before you trust a bulk run on a client account. With partial_failure set to false, later operations are skipped after one fails, but OpenAI states this setting does not roll back operations that already completed. There is no transaction. A failed job can leave a campaign created and its ad group missing.

validate_only has a similar limit. OpenAI states that validation-only jobs do not guarantee operations can complete successfully, because they do not check update-target existence, image fetching, entity limits or other write-time errors. It catches malformed requests and broken references, not everything that can go wrong at write time.

SettingWhat it doesWhat it does not do
partial_failure: trueKeeps running independent operations after a failureDoes not retry the failed one
partial_failure: falseSkips later operations after a failureDoes not roll back operations already completed
validate_only: trueChecks fields and dependencies, changes nothingDoes not check update-target existence, image fetching, entity limits or other write-time errors

The practical rule for agencies in 2026: always create bulk resources as paused, as OpenAI's example does, so a half-completed job leaves inert objects rather than partially-built live campaigns spending money.

Which Operations Does the Bulk API Support?

Six operation types: create and update for each of campaigns, ad groups and ads. Every entry needs a unique operation_id, a type and an input object. Creates also need a unique idempotency_key; updates need a target_resource_id and at least one input field.

TypeRequired inputOther supported input
campaign.createname, max_budget_microsbilling_event_type, budget_type, status, target_countries, location_ids
campaign.updateAt least one supported fieldname, description, status, max_budget_micros, budget_type, start_time, end_time and others
ad_group.createcampaign_idempotency_key, namecontext_hints, exclusion_hints, max_bid_micros, max_cpm_bid_micros, status
ad_group.updateAt least one supported fieldname, description, status, context_hints, exclusion_hints, bids
ad.createcampaign_idempotency_key, ad_group_idempotency_key, title, body, target_url, source_image_urlstatus
ad.updateAt least one supported fieldname, status, creative

The defaults and limits that catch people out

How Do Parent and Child References Work in One Job?

Through idempotency keys rather than IDs, because the IDs do not exist yet when you submit. Set campaign_idempotency_key on an ad group to the campaign operation's key, and set ad_group_idempotency_key on an ad to the ad group operation's key. OpenAI adds that the campaign reference on ad.create must match the campaign reference on its parent ad_group.create.

Three rules constrain how you can mix operations. You can combine creates and updates in one job. Updates can only target resources that exist when you submit, so you cannot update something created in the same job. And each resource can be updated only once per job. If your tooling generates changes from a diff, deduplicate per resource before submitting.

How Do You Track a Job and Read the Results?

Poll the job until it reaches a terminal status, then page through the per-operation results. completed, partially_failed and failed are terminal.

curl -X GET   "https://api.ads.openai.com/v1/bulk_mutation_jobs/blkmtnjob_6a2b773d47b481908aa6078025a64ad3"   -H "Authorization: Bearer $OPENAI_ADS_API_KEY"
Job statusMeaning
pendingWaiting to run
in_progressProcessing operations
completedAll operations completed successfully
partially_failedAt least one succeeded and another failed or was skipped
failedNo operations succeeded

Results come from GET /bulk_mutation_jobs/{job_id}/operations, 1 to 100 per page, defaulting to 100. Each result carries its operation_id, type, status and nullable error fields. OpenAI notes that pagination cursors are only available after complete is true, and that while a job is running the endpoint can return an incomplete snapshot. Do not treat a mid-run read as final.

Operation statusMeaning
createdThe create succeeded
updatedThe update succeeded
validatedPassed validation in a validation-only job
failedReturned an error; check retryable and retry_after_seconds
skippedDid not run because a dependency or earlier operation failed

What Are the Limits and Retry Rules?

The limits are generous for a single client and tight for an agency running many accounts in parallel, mainly because of the create rate.

LimitValue
Operations per job1,000
Request body size16 MiB
Serialised operation size512 KiB
Create requests per ad account10 requests per 10 seconds
Operation results per page100
Self-serve campaigns per ad account5,000 non-archived
Self-serve ad groups per ad account5,000 non-archived
Self-serve ads per ad account5,000 active or paused
operation_id and idempotency key lengthUp to 255 characters

Retries have two layers. The request-level Idempotency-Key header makes it safe to retry an uncertain request with the same body; reusing it with a different body returns an error. To rerun a failed or partially_failed job, submit the same body with a new request-level key, and OpenAI states successful creates are reused. At operation level, if a result is retryable, wait for retry_after_seconds where provided, then resubmit in a new job reusing the original create-operation idempotency_key values.

How Should an Agency Use the Bulk API Safely?

Treat it as a deployment tool with the same discipline you would apply to production code. The documentation gives you the primitives for safe operation; the workflow is yours to impose.

  1. Confirm access per client account before building a workflow around it, since it is limited preview and enabled per account.
  2. Run validate_only first, knowing it does not catch write-time errors.
  3. Create everything paused so a partial job cannot leave live spend behind.
  4. Use deterministic idempotency keys derived from your own campaign naming, so retries reuse rather than duplicate.
  5. Read all results only after complete is true, then reconcile failed and skipped operations.
  6. Activate deliberately afterwards, through the standard endpoints, once each level is verified.
  7. Pace jobs across accounts to stay inside 10 create requests per 10 seconds per account.

One header detail matters for multi-client tooling: OpenAI states each Ads API key works with one ad account, so you do not add an OpenAI-Ad-Account header when using an API key. Account switching is therefore a key-management problem, which pushes agencies toward a proper secrets store per client rather than a shared credential. The account management section covers the partner-side setup.

What Are the Common Bulk API Mistakes?

What Are the Common Mistakes With the ChatGPT Ads API in 2026?

Key Takeaways for 2026

ChatGPT Ads in 2026 is a real auction platform with its own structural logic, and most of the early mistakes come from carrying Meta or Google habits across unchanged.

Distk builds and runs paid media for growth teams across India and internationally, including the measurement layer that makes a new channel readable rather than a guess. If you are evaluating ChatGPT Ads in 2026, the sensible first step is a small structured test with tracking verified end to end before any budget scales, and that is the piece we would set up with you.

Sources

Every endpoint, field, limit and default in this guide is quoted from OpenAI's published Ads documentation as of 30 September 2026. Platform capabilities change; check the changelog before relying on any specific behaviour.

ChatGPT Ads API in 2026: FAQs

What is the base URL and authentication for the ChatGPT Ads API?

Requests go to https://api.ads.openai.com with an Authorization bearer header. You create the Advertiser API key in the Settings page of Ads Manager at ads.openai.com. Each key works with one ad account, so you do not add an account header when using it.

What bid strategies does ChatGPT Ads support in 2026?

Three: fixed_bid, where you supply max_bid_micros, plus maximize_clicks and maximize_conversions, which OpenAI brands jointly as Maximize Results and which let OpenAI adjust bids within a daily budget. Both Maximize strategies are available for standard and product-feed campaigns.

Why is my Maximize Results ad group failing to create?

Check five things: the campaign needs a daily budget rather than lifetime, billing_event_type must be click, max_bid_micros must be omitted, audience bid multipliers must not be set, and an Idempotency-Key header is required for Maximize Results ad group creation.

How do I set a CPM bid in the ChatGPT Ads API?

The API expects a bid per impression, not per thousand impressions. Divide your CPM by 1,000 then multiply by 1,000,000. OpenAI's own example: a 60 USD CPM is 0.06 USD per impression, so you send 60000 micros.

What cannot be changed after a ChatGPT Ads campaign is created?

The campaign objective, the selected conversion event on a conversion-optimised campaign, and a daily budget cannot be switched back to lifetime. An ad also cannot be moved to a different ad group, and account currency and timezone are creation-time choices.

Why is my ChatGPT Ads campaign not delivering after activation?

Activation only permits delivery. Check account status and account reviews, the account spend limit, the campaign budget and schedule, targeting, the ad group bid using the bid_too_low include, and ad review status. Campaign budgets and account spend limits apply independently.

Why did my ChatGPT ads stop after I changed the brand name?

OpenAI states that changing the legal or public brand name pauses ad delivery until the account passes review. Any rename, including a typo fix, stops every ad in the account until review completes, so set the public name correctly before launch.

Do conversion-optimised ChatGPT campaigns charge per conversion?

No. OpenAI states that billing does not change to pay per conversion. Delivery optimises toward your selected conversion event, but you are charged only when a valid click occurs, and the auction determines the actual CPC.

Is targeting set on the campaign or the ad group in ChatGPT Ads?

Geographic, platform and custom audience targeting are all campaign-level. Context hints and audience bid multipliers are ad-group-level. That means a targeting variation requires a new campaign with its own budget, unlike platforms where ad sets carry targeting under a shared campaign budget.

What is the difference between pixel_id and id in ChatGPT Ads?

A data source returns both. The pixel_id initialises the Measurement Pixel, sends server events and checks recent events. The id selects the source when creating a conversion event setting, so it goes in source_ids. Using the wrong one is the most common setup error.

Is the ChatGPT Ads Bulk API available to every account?

No. OpenAI states it is in limited preview and enabled per ad account, and it is not included in the downloadable OpenAPI spec. If a bulk endpoint returns 404, contact your OpenAI account team to confirm access for the account tied to your Ads API key.

Test a new channel properly before you scale it

Distk sets up paid media on new platforms with tracking verified end to end first, so the data you get back tells you whether the message worked rather than whether the plumbing was broken.

Start the conversation →