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
| Level | What you configure here | What this means for a media buyer |
|---|---|---|
| Ad account | Advertiser branding, currency, timezone, account access, spend limits | Currency and timezone are creation-time choices and cannot be edited later. |
| Campaign | Objective, budget, schedule, geographic and platform targeting, audience inclusion and exclusion, conversion events | Targeting lives here, not on the ad group. One budget is shared across all its ad groups. |
| Ad group | Bid strategy, context hints, audience bid multipliers, product set | This is your bidding and relevance layer. |
| Ad | Creative, image or product template, destination URL | An 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.
| Field | Purpose | Who sees it |
|---|---|---|
legal_name | Legal business name | Review and billing context |
account_name | Internal name shown in Ads Manager | Your team and your agency |
brand_name | Public advertiser name shown in ads | People 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"
}'
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}"
| Field | What it tells you |
|---|---|
status | Whether the account is configured as active or paused |
review.status | Brand-review state |
review.reason | Reason for a brand-review issue, when available |
account_integrity_review.review.status | A 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 rule | What OpenAI documents |
|---|---|
| Overlap | Windows cannot overlap |
| Future windows | You can schedule up to 60 |
| Active window start date | Cannot be changed |
| Reducing the amount | Cannot go below spending that has already occurred |
| Completed windows | Cannot be edited or deleted |
| Deleting or raising an exhausted active limit | Can 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.
| Status | What to do |
|---|---|
400 | Correct missing or malformed fields, including invalid dates or dates outside 2000-01-01 to 2100-01-01 |
409 | Refresh the list and reconcile a stale revision or configuration conflict before resubmitting |
422 | Correct the amount, date ordering, overlapping limits, or a change to a completed window. A decrease below recorded spend returns budget_window_amount_below_spend |
503 | Refresh 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?
- Changing the brand name mid-campaign. It pauses delivery until review passes.
- Choosing the wrong currency or timezone. Both are creation-time choices that cannot be edited later.
- Reading an omitted review object as approval. OpenAI says not to interpret it as approval or rejection.
- Assuming an active account means delivery. Reviews, spend limits and campaign issues can each block it.
- Raising a campaign budget to fix an exhausted account limit. They apply independently.
- Retrying a 503 blindly. The change may have succeeded; refresh first.
- Using the legacy
namefield with individual names. It overwrites all three. - Storing
preview_urlas the icon's permanent URL. It is a preview, not a durable asset.
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.
| Objective | Best for | How you pay | What delivery optimises for |
|---|---|---|---|
impressions (CPM) | Reach and awareness | Per 1,000 impressions | Broad delivery at scale |
clicks (CPC) | Engagement and traffic | Per valid click | Clicks from people likely to engage |
conversions (oCPC) | A tracked action after a click | Per valid click, not per conversion | Clicks 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.
| Strategy | Use when | Compatible objectives | Budget | Bid amount |
|---|---|---|---|---|
fixed_bid | You want to set and adjust the bid yourself | Impressions, clicks, conversions | Daily or lifetime | Provide max_bid_micros |
maximize_clicks | You want OpenAI to seek more clicks from your budget | Clicks | Daily only | Omit max_bid_micros |
maximize_conversions | You want OpenAI to seek more conversions from your budget | Conversions | Daily only | Omit 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_type | Ad group billing_event_type | Ad group strategy |
|---|---|---|
impressions | impression | fixed_bid |
clicks | click | fixed_bid |
clicks | click | maximize_clicks |
conversions | click | fixed_bid |
conversions | click | maximize_conversions |
The Maximize Results prerequisites people miss
- Daily budget required. Maximize Results does not work with a lifetime budget.
- Click billing required. Both strategies use
billing_event_type: "click". - Omit the bid. Sending
max_bid_microswith a Maximize strategy is a configuration error. - No audience bid multipliers. Those work only with
fixed_bid. - An
Idempotency-Keyis required when creating a Maximize Results ad group. It is optional elsewhere on create endpoints and mandatory here. - For conversions, the campaign needs exactly one active standard conversion event setting.
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.
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.
- The ad account must support conversion bidding. If campaign creation returns
403withConversion bidding is not enabled, OpenAI's instruction is to contact your OpenAI partner representative. This is an account-level gate. - 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.
- You need exactly one active standard conversion event to use as the optimisation goal. Custom events cannot be oCPC optimisation goals.
- 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 goal | Standard event to optimise toward |
|---|---|
| E-commerce purchase | order_created |
| Lead form or contact request | lead_created |
| Account or event signup | registration_completed |
| Demo or consultation booked | appointment_scheduled |
| Paid subscription started | subscription_created |
| Free trial started | trial_started |
| Bespoke action, such as a quote request | Not 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 want | Allowed? | What to do |
|---|---|---|
| Convert an existing CPM or CPC campaign to oCPC | No | Create a new campaign with bidding_type: "conversions" |
| Change the selected conversion event | No | Create a new campaign optimising toward the new event |
| Change the campaign goal | No | Create a new campaign |
| Switch between a fixed CPA bid and Maximize conversions | Yes, within the same objective | Update the ad group's bidding_config, respecting budget rules |
| Adjust the CPA bid amount | Yes | Update 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:
- Choose the standard conversion event that best represents your campaign goal.
- Keep conversion tracking healthy. Incomplete or incorrectly configured tracking makes reporting and optimisation less effective.
- Use a conversion event with enough volume to evaluate performance.
- Align ad copy with user intent and the selected conversion goal.
- Review enough volume before making large changes to bids, budgets or creative.
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?
- Reading the CPA bid as the price. It is an optimisation input. You pay per valid click, and your actual cost per conversion is spend divided by conversions.
- Launching before tracking is verified. Billing continues on clicks while optimisation learns from a misfiring event.
- Choosing a custom event as the goal. Custom events cannot be oCPC optimisation goals.
- Expecting to convert a CPC campaign in place. You cannot. Build a new campaign.
- Picking an event with too little volume. OpenAI explicitly advises enough volume to evaluate performance.
- Pairing Maximize conversions with a lifetime budget. Maximize Results needs a daily budget.
- Treating the 403 as a bug.
Conversion bidding is not enabledis an account gate; contact your OpenAI partner representative. - Making large changes on thin data. Review enough volume before adjusting bids, budgets or creative.
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 account | Value to send |
|---|---|
| 1.00 USD | 1000000 |
| 2.50 USD | 2500000 |
| 50.00 USD | 50000000 |
| 500.00 USD lifetime | 500000000 |
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.
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.
| Setting | Changeable? | What to do instead |
|---|---|---|
Campaign objective (bidding_type) | No | Create a new campaign. |
| Selected conversion event on an oCPC campaign | No | Create a new campaign. |
| Daily budget back to lifetime | No | Create a new campaign. |
| Moving an ad to a different ad group | No | Create the ad in the target ad group. |
| Account currency and timezone | No | Set correctly at account creation. |
| Bid strategy within the same objective | Yes | Update bidding_config, respecting the budget rules. |
| Creative | Yes | Updating 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.
| Limit | Value |
|---|---|
| Per endpoint | 600 requests per minute |
| Overall | 1,200 requests per minute |
| Bulk job creation | 10 requests per 10 seconds per ad account |
| Self-serve campaigns per ad account | 5,000 non-archived |
| Self-serve ad groups per ad account | 5,000 non-archived |
| Self-serve ads per ad account | 5,000 active or paused |
| Location IDs per campaign | 2,500 |
| Context hints per ad group | 2,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.
| Metrics | Freshness | Reporting history available |
|---|---|---|
| Impressions, clicks, CTR | Can appear within minutes; recent values may change | Hourly: about 30 days |
| Spend, CPC, CPM | Reflect finalised activity and can update later | Non-hourly, excluding product: most recent 365 days |
| Conversions and purchase outcomes | Daily processing; allow at least one day to appear | Product 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.
- 10 September 2026: granular web platform targeting with
desktop_web,ios_webandandroid_web. - 9 September 2026: daily account spending limits for accounts on postpaid invoice billing.
- 25 August 2026: custom audience Add, Remove, Replace and Merge operations, automatic identifier matching, and support for small and empty exclusion-only audiences.
- 16 July 2026: support for passing the Pixel browser reference as
events[].user.obrefin Conversions API requests. - 16 June 2026: conversion-optimised campaign bidding with
bidding_type: "conversions". - 11 June 2026: segmented insights for product, country and device breakdowns.
- 3 June 2026: location targeting including
/geo_lookup/search, plus conversion setup and reporting endpoints.
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.
| Primitive | Level | Field | What it does |
|---|---|---|---|
| Geographic | Campaign | targeting.locations, targeting.excluded_locations | Country codes or location IDs, with exclusions |
| Platform | Campaign | targeting.platforms.included | Which ChatGPT surfaces can deliver |
| Custom audiences | Campaign | targeting.custom_audiences, targeting.excluded_custom_audiences | First-party lists for inclusion or exclusion |
| Context hints | Ad group | context_hints | Describes the offering so the platform can judge relevance |
| Audience bid multipliers | Ad group | bidding_config.custom_audience_bid_multipliers | Adjusts 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.
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 value | Platform | Includes |
|---|---|---|
ios_app | iOS app | The native ChatGPT app on iOS |
android_app | Android app | The native ChatGPT app on Android |
desktop_web | Desktop web | ChatGPT in a desktop web browser |
ios_web | iOS web | ChatGPT in a web browser on iOS |
android_web | Android web | ChatGPT in a web browser on Android |
web | Web | All 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 use | Size requirement | What it means in practice |
|---|---|---|
exclusion | Ready small or empty audiences can be used, with no minimum matched size | Suppression works at any list size, including an empty list you add to later |
inclusion | Must meet the matched-user minimum | Targeting your customer list needs scale |
bid_multiplier | Must meet the matched-user minimum | Bid 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.
| Action | Endpoint | Input |
|---|---|---|
| Add members, keeping existing ones | POST /v1/custom_audiences/{id}/add | Inline identifiers or an uploaded file |
| Remove selected members | POST /v1/custom_audiences/{id}/remove | Inline identifiers or an uploaded file |
| Replace the complete list | POST /v1/custom_audiences/{id}/replace | An uploaded file |
| Merge existing audiences | Merge operation | 2 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 useful | More useful |
|---|---|
| Shoes | Lightweight trail running shoes for rocky terrain |
| Outdoors | Water-resistant footwear for wet-weather hiking |
| California customers | Use 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?
- Sending a partial targeting update. Geographic and audience updates can replace existing criteria. Read first, send the complete object, verify after.
- Reading
webas desktop. It includes mobile browsers. Usedesktop_webfor desktop only. - Assuming uploaded rows equal matched users. They do not, and 25,000 identifiers does not guarantee 25,000 matches.
- Planning inclusion targeting on a small CRM list. Exclusion works at any size; inclusion and bid multipliers need the minimum.
- Confusing a bid multiplier with inclusion. Multipliers do not restrict who is eligible.
- Pairing multipliers with Maximize Results. They work only with fixed bidding.
- Expecting sub-country targeting on product-feed campaigns. New ones support country level only.
- Writing context hints as keywords. They are descriptions, not match types, and geography belongs in targeting.
- Planning audience targeting for EEA or Swiss campaigns. Custom audiences are not supported there.
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.
| Object | What it does | Created by |
|---|---|---|
| Data source (pixel) | Receives events from browser or server | POST /v1/conversions/pixels |
| Conversion event setting | Defines which event counts as a conversion, with an attribution window | POST /v1/conversions/event_settings |
| Campaign attachment | Connects the setting to a campaign for reporting or optimisation | conversion_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.
| Integration | Where events are sent | When to use it |
|---|---|---|
| Measurement Pixel | The customer's browser | Measure actions that happen on your website |
| Conversions API | Your server | Send actions recorded by your server, such as confirmed orders |
| Both | Browser and server | Measure 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.
| Directive | Source | Purpose |
|---|---|---|
script-src | https://bzrcdn.openai.com | Load the Measurement Pixel SDK |
connect-src | https://bzr.openai.com | Send events with fetch or sendBeacon |
connect-src | https://bzrcdn.openai.com | Fetch per-pixel configuration |
img-src | https://bzr.openai.com | Send 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.
| Cookie | Expiry | What it stores and how it refreshes |
|---|---|---|
__oppref | 30 days after the pixel writes it | The 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. |
__obref | 365 days after creation | A 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.
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 name | Data type | Use for |
|---|---|---|
order_created | contents | A purchase is completed |
checkout_started | contents | A user starts checkout |
items_added | contents | Items added to a cart, bundle or selection |
contents_viewed | contents | A product, listing or article is viewed |
page_viewed | contents | An important page loads |
lead_created | customer_action | A lead form is submitted or contact requested |
registration_completed | customer_action | Account or event registration finishes |
appointment_scheduled | customer_action | A meeting, demo or consultation is booked |
subscription_created | plan_enrollment | A paid subscription starts |
trial_started | plan_enrollment | A free trial starts |
app_installed | customer_action | An app install. Conversions API only, with action_source: mobile_app |
app_opened | customer_action | An app open. Conversions API only |
custom | custom | Anything 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?
- Using
pixel_idwhere the API wantsid. Event settings take the source'sidinsource_ids. - Forgetting the CSP entries. A strict policy blocks the SDK or the event send with no visible error on the page.
- Not capturing
opprefon the landing page. The Conversions API will not capture it for you, so server-side attribution degrades. - Different event IDs per integration. That produces double-counted conversions, which then feed optimisation.
- Sending amounts in major units. Values are integers in the currency's minor unit, so 89.00 USD is 8900.
- Trying to send app events from the pixel.
app_installedandapp_openedare Conversions API only. - Reading view-through numbers as part of Conversions. They are a separate campaign-level metric and do not affect bidding or billing.
- Leaving consent at the default without a decision. It initialises to true unless you set it otherwise, which is a choice your privacy review should make deliberately.
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.
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.
- One submission for a whole structure. Campaign, ad groups and ads in a single job, linked by idempotency keys rather than returned IDs.
- Per-operation results. Every operation reports created, updated, validated, failed or skipped, with retry guidance on failures.
- A dry-run mode.
validate_onlychecks fields and dependencies without changing anything. - Safer retries. Idempotency at both the request and operation level, so a rerun reuses successful creates.
- A separate rate limit. Bulk job creation has its own budget distinct from the standard per-endpoint limits.
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
| Field | Required | What it does |
|---|---|---|
operations | Yes | Between 1 and 1,000 create or update operations |
validate_only | No | Validates fields and dependencies without changing resources. Defaults to false |
partial_failure | No | Continues 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.
| Setting | What it does | What it does not do |
|---|---|---|
partial_failure: true | Keeps running independent operations after a failure | Does not retry the failed one |
partial_failure: false | Skips later operations after a failure | Does not roll back operations already completed |
validate_only: true | Checks fields and dependencies, changes nothing | Does 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.
| Type | Required input | Other supported input |
|---|---|---|
campaign.create | name, max_budget_micros | billing_event_type, budget_type, status, target_countries, location_ids |
campaign.update | At least one supported field | name, description, status, max_budget_micros, budget_type, start_time, end_time and others |
ad_group.create | campaign_idempotency_key, name | context_hints, exclusion_hints, max_bid_micros, max_cpm_bid_micros, status |
ad_group.update | At least one supported field | name, description, status, context_hints, exclusion_hints, bids |
ad.create | campaign_idempotency_key, ad_group_idempotency_key, title, body, target_url, source_image_url | status |
ad.update | At least one supported field | name, status, creative |
The defaults and limits that catch people out
campaign.createdefaults to an impression-billed, lifetime, paused campaign. If you omit billing and budget type, that is what you get, which is not what most performance campaigns want.- Campaign budget must be at least
1000000currency micros, which is one unit of the account currency. - Ad group bids must match the parent's billing event. Provide only one of
max_bid_microsfor clicks ormax_cpm_bid_microsfor impressions. OpenAI notes CPM requires account access. - Names run 3 to 1,000 characters for campaigns and ad groups. Ad titles allow 3 to 50, bodies up to 100, URLs up to 2,048.
- Campaigns support up to 2,500 location IDs, and ad groups up to 2,000 context hints.
- Create statuses are
activeorpaused; update statuses also supportarchived. - Updating an ad creative requires
title,body,target_urlandfile_idtogether.
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 status | Meaning |
|---|---|
pending | Waiting to run |
in_progress | Processing operations |
completed | All operations completed successfully |
partially_failed | At least one succeeded and another failed or was skipped |
failed | No 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 status | Meaning |
|---|---|
created | The create succeeded |
updated | The update succeeded |
validated | Passed validation in a validation-only job |
failed | Returned an error; check retryable and retry_after_seconds |
skipped | Did 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.
| Limit | Value |
|---|---|
| Operations per job | 1,000 |
| Request body size | 16 MiB |
| Serialised operation size | 512 KiB |
| Create requests per ad account | 10 requests per 10 seconds |
| Operation results per page | 100 |
| Self-serve campaigns per ad account | 5,000 non-archived |
| Self-serve ad groups per ad account | 5,000 non-archived |
| Self-serve ads per ad account | 5,000 active or paused |
operation_id and idempotency key length | Up 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.
- Confirm access per client account before building a workflow around it, since it is limited preview and enabled per account.
- Run
validate_onlyfirst, knowing it does not catch write-time errors. - Create everything paused so a partial job cannot leave live spend behind.
- Use deterministic idempotency keys derived from your own campaign naming, so retries reuse rather than duplicate.
- Read all results only after
completeis true, then reconcile failed and skipped operations. - Activate deliberately afterwards, through the standard endpoints, once each level is verified.
- 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?
- Assuming bulk is available everywhere. It is limited preview, enabled per ad account, and absent from the OpenAPI spec.
- Expecting rollback.
partial_failure: falseskips later operations but does not undo completed ones. - Trusting
validate_onlyas a full test. It skips update-target existence, image fetching and entity-limit checks. - Omitting billing and budget type.
campaign.createdefaults to impression-billed and lifetime. - Updating a resource created in the same job. Updates can only target resources that exist at submission.
- Reading results mid-run. The snapshot can be incomplete until
completeis true. - Generating new idempotency keys on retry. Reuse the original create-operation keys so successful creates are reused.
- Creating resources active. A partial job then leaves partially-built live campaigns.
What Are the Common Mistakes With the ChatGPT Ads API in 2026?
- Sending a CPM bid per thousand instead of per impression. A 60 USD CPM is
60000micros, not 60000000. - Pairing Maximize Results with a lifetime budget. It requires a daily budget, and the switch back to lifetime is not available.
- Forgetting the mandatory
Idempotency-Keywhen creating a Maximize Results ad group. - Sending a partial targeting update. Geographic and audience updates can replace existing criteria, so retrieve the campaign and send the complete intended configuration.
- Assuming a budget update adds to the old budget. It replaces it.
- Treating activation as delivery. Account reviews, spend limits, creative review and targeting can each independently block serving.
- Judging a campaign on day-one conversion data. Conversions update through daily processing, so allow at least a day.
- Planning one campaign with several differently-targeted ad groups. Targeting is a campaign-level setting on this platform.
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.
- Base URL
https://api.ads.openai.com, bearer auth, keys created in Ads Manager Settings, and one key per ad account. - Four levels: account, campaign, ad group, ad. Targeting sits on the campaign, bidding on the ad group.
- Three objectives and three bid strategies, but only five valid combinations of objective, billing event and strategy.
- Maximize Results needs a daily budget, click billing, no explicit bid, no audience multipliers and a mandatory idempotency key.
- Budgets and bids are in micros; impression bids are per impression, not per thousand.
- Everything is created paused, and you activate from the ad upward.
- Objective, oCPC event, daily-to-lifetime budget and an ad's parent ad group are all fixed after creation.
- Rate limits are 600 per endpoint and 1,200 overall per minute, enforced by both account and IP.
- Conversion reporting needs at least a day, and CTR comes back as a ratio.
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
- OpenAI, Ads API Overview, including campaign structure, first campaign, rate limits and changelog.
- OpenAI, Bidding and Budgets.
- OpenAI, Campaign Management, including creative limits and tracking parameters.
- OpenAI, Reporting, including metric definitions, data freshness and retention.
- OpenAI, Ads documentation index.
- OpenAI, Account Management, including branding, statuses and reviews, activation and spend limits.
- OpenAI, Ad Account API reference, including daily limits and error handling.
- OpenAI, API Partner Setup.
- OpenAI, Conversion-Optimized Campaigns, including prerequisites, billing, product-feed oCPC and common questions.
- OpenAI, Supported Events.
- OpenAI, Conversion Tracking.
- OpenAI, Targeting, including inclusion and exclusion, geographic, platform and context hints.
- OpenAI, Custom Audiences, including eligibility thresholds, file rules and the EEA restriction.
- OpenAI, Platform Targeting.
- OpenAI, Location Targeting.
- OpenAI, Ad Tools Terms.
- OpenAI, Measurement Pixel, including install, consent, CSP, advanced matching and cookie expiry.
- OpenAI, Conversions API.
- OpenAI, Conversion Setup API reference.
- OpenAI, Bulk API, including operations, job statuses, limits and retries.
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.