ChatGPT Ads

ChatGPT Ads shows a chat card (a title, a short body, an image and a link) inside ChatGPT. You connect it with an API key instead of OAuth, create a campaign in one request, and measure it with a pixel on your site plus server-side conversions. The connection platform is openaiads and the ad endpoints call the network openai.

Only businesses based in the US can use ChatGPT Ads Manager. The ads are shown to people on the ChatGPT Free and Go plans in the United States, Canada, Australia and New Zealand.

#Connect with an API key

Create a key in ChatGPT Ads Manager under Settings. A key belongs to exactly one ad account, so connect each ad account with its own key.

curl -X POST https://api.pozy.ai/v1/connect/openai-ads/credentials \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "sk-ads-...", "profileId": "66b2e19d8c3f5a7e9d0b1c2a" }'

const res = await fetch("https://api.pozy.ai/v1/connect/openai-ads/credentials", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ apiKey: process.env.CHATGPT_ADS_KEY!, profileId: "66b2e19d8c3f5a7e9d0b1c2a" }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.accountId, data.adAccountName);

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/connect/openai-ads/credentials",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={"apiKey": os.environ["CHATGPT_ADS_KEY"], "profileId": "66b2e19d8c3f5a7e9d0b1c2a"},
)
print(resp.json())

{ "accountId": "66b2e19d8c3f5a7e9d0b1c2d", "adAccountName": "Acme US" }

Before saving, Pozy tests the key on the ad account. Sending a new key for an ad account you already connected updates that connection rather than adding another. The dashboard can connect it too.

#Create a campaign

POST /v1/ads/create builds the campaign, ad group and chat card. This example runs a lifetime budget with a fixed bid until the end date:

curl -X POST https://api.pozy.ai/v1/ads/create \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: planner-launch-chatgpt" \
  -d '{
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "adAccountId": "acct_abc123",
    "name": "Planner launch",
    "goal": "traffic",
    "budgetAmount": 25,
    "budgetType": "lifetime",
    "endDate": "2027-02-28T23:59:00Z",
    "bidStrategy": "LOWEST_COST_WITH_BID_CAP",
    "bidAmount": 2,
    "headline": "Try the new planner",
    "body": "Tasks, docs and meetings in one place.",
    "imageUrl": "https://cdn.example.com/planner.png",
    "linkUrl": "https://example.com/planner",
    "countries": ["US"]
  }'

const res = await fetch("https://api.pozy.ai/v1/ads/create", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Idempotency-Key": "planner-launch-chatgpt",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accountId: "66b2e19d8c3f5a7e9d0b1c2d",
    adAccountId: "acct_abc123",
    name: "Planner launch",
    goal: "traffic",
    budgetAmount: 25,
    budgetType: "lifetime",
    endDate: "2027-02-28T23:59:00Z",
    bidStrategy: "LOWEST_COST_WITH_BID_CAP",
    bidAmount: 2,
    headline: "Try the new planner",
    body: "Tasks, docs and meetings in one place.",
    imageUrl: "https://cdn.example.com/planner.png",
    linkUrl: "https://example.com/planner",
    countries: ["US"],
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.ad.status);

resp = requests.post(
    "https://api.pozy.ai/v1/ads/create",
    headers={
        "Authorization": f"Bearer {os.environ['POZY_API_KEY']}",
        "Idempotency-Key": "planner-launch-chatgpt",
    },
    json={
        "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
        "adAccountId": "acct_abc123",
        "name": "Planner launch",
        "goal": "traffic",
        "budgetAmount": 25,
        "budgetType": "lifetime",
        "endDate": "2027-02-28T23:59:00Z",
        "bidStrategy": "LOWEST_COST_WITH_BID_CAP",
        "bidAmount": 2,
        "headline": "Try the new planner",
        "body": "Tasks, docs and meetings in one place.",
        "imageUrl": "https://cdn.example.com/planner.png",
        "linkUrl": "https://example.com/planner",
        "countries": ["US"],
    },
)
print(resp.json()["ad"]["status"])

{
  "ad": {
    "_id": "66f0a1b2c3d4e5f6a7b8c9d0",
    "name": "Planner launch",
    "platform": "openai",
    "status": "pending_review",
    "adType": "standalone",
    "goal": "traffic",
    "budget": { "amount": 25, "type": "lifetime" }
  },
  "message": "Ad created"
}

budgetAmount and bidAmount are whole units of the ad account currency; the ad's currency field names it.

#Budget

A ChatGPT campaign has exactly one spend cap:

The minimum is 1 in the ad account currency (422 below that). Some currencies have a higher daily minimum, which is only checked on a real create; the error names the amount.

#Bidding

Automatic bidding on a lifetime budget or on awareness returns 400 missing_required_field with param: "bidStrategy"; send a fixed bid there. There is no ROAS bidding, so LOWEST_COST_WITH_MIN_ROAS returns 422.

#Status at launch

With status: "PAUSED", only the campaign is paused and its ad group and ad are left on, so a single PUT /v1/ads/campaigns/{campaignId}/status with active starts it all. Add campaignStatus: "ACTIVE" to flip that around: the campaign runs and the ad group holds the pause. Send neither and the ad starts as soon as it passes review.

#Targeting

Countries are the only targeting. Ages, genders, interests and audiences return 400 instead of being ignored. Custom audiences are managed in Ads Manager only.

#Optimize for a conversion

goal: "conversions" needs an optimizable conversion event on the ad account before you create the campaign. Create one with the pixel (defaultEventType, below) or in Ads Manager.

Pick the event with promotedObject.customEventType. Read the candidates from conversionEvents[] on GET /v1/accounts/{accountId}/conversion-destinations:

{
  "conversionEvents": [
    { "id": "evs_123", "name": "Purchase", "eventType": "order_created", "customEventName": null, "archived": false, "optimizable": true }
  ]
}

Pass the event's id, its eventType (such as order_created) or its name (such as Purchase):

{ "goal": "conversions", "promotedObject": { "customEventType": "order_created" } }

• Only optimizable events qualify: active, standard events, not custom ones.
• If the event is unknown, archived or custom, you get 400 with the events the account can optimize for. If several events share the name, the 400 asks you to send the id.
• Without customEventType, the campaign optimizes for the most recently created optimizable event.
• customEventType is the only promotedObject field ChatGPT Ads accepts, and only with conversions.

#Click tracking

Every click adds tracking.urlTags to the end of linkUrl. Pozy leaves ChatGPT's macros {campaign_id}, {ad_group_id}, {ad_id} and {oppref} (the click id) unescaped there, so ChatGPT fills them in on the click. Macros written into linkUrl itself stay as literal text.

{
  "tracking": {
    "urlTags": [
      { "key": "utm_source", "value": "chatgpt" },
      { "key": "utm_campaign", "value": "{campaign_id}" },
      { "key": "click_id", "value": "{oppref}" }
    ]
  }
}

#Check before you spend

Send validateOnly: true to test a request without creating anything. Pozy checks copy lengths, budget, bid strategy and targeting, and looks up the conversion event and countries live.

{
  "validateOnly": true,
  "results": [
    { "node": "campaign", "status": "validated" },
    { "node": "adSet", "status": "validated" },
    { "node": "ad", "status": "validated" }
  ],
  "message": "..."
}

Checks that only run at write time, such as fetching the image, currency minimums and ad review, still happen on the real create. POST /v1/ads/campaigns also takes validateOnly.

#Manage a running campaign

Targeting and creative cannot change after launch (501 feature_not_available). There is no boost, because ChatGPT has no organic posts, and no video.

GET /v1/ads/tree reports two kinds of status on ChatGPT Ads: status (is it delivering, inherited from parents) and the levels' own switches (platformCampaignStatus on campaigns, configuredStatus on ads, each active/ACTIVE, paused or archived). Objects archived in Ads Manager settle as archived in Pozy.

#Measure results

Pozy syncs impressions, clicks and spend once a day and derives CTR, CPC and CPM. GET /v1/ads/{adId}/analytics defaults to the last 90 days. Every other metric, reach included, reads 0, and demographic breakdowns are not available. History starts 90 days before the connection.

#The pixel

The pixel measures what people do on your site after a chat card. Manage it through the tracking tags endpoints on the openaiads connection.

curl -X POST https://api.pozy.ai/v1/accounts/66b2e19d8c3f5a7e9d0b1c2d/tracking-tags \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "adAccountId": "acct_abc123", "name": "Acme website", "defaultEventType": "order_created" }'

• One call creates the pixel and a Conversions API key for it. defaultEventType also creates the conversion event a conversions campaign needs.
• adAccountId is required by the endpoint but the API key already decides the ad account.
• Each pixel has two ids, and per-pixel calls accept either: tag.id (cds_...) and tag.siteTagId (also pixelId), the id the site code and the Conversions API send.
• Pozy creates one pixel per connection; a second create returns 409. Creating is not idempotent and pixels cannot be deleted, so never retry it automatically. After a 502, list the pixels first.
• GET .../tracking-tags/{tagId}/stats shows the latest events received, up to 50 from the last 15 minutes. Use it to check the pixel fires, not for totals.

Conversion events take name, type and siteEvent, with ChatGPT's fixed 30-day window. type is a standard event (order_created, lead_created, items_added, contents_viewed, checkout_started, registration_completed, subscription_created, trial_started, appointment_scheduled, page_viewed, app_installed, app_opened) or a custom name of 1 to 64 letters, digits, _ or -. To edit or remove an event, or the pixel, use Ads Manager: the API cannot.

Install the pixel on a connected Shopify, WordPress, Wix or Webflow site with one call. See Pixels.

#Conversions API

Server-side events go to POST /v1/ads/conversions with the pixel's site id as destinationId. A pixel must exist first (422 tracking_tag_required otherwise).

curl -X POST https://api.pozy.ai/v1/ads/conversions \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "destinationId": "4Kx9TqLm2VbN7wRz1PsYcD",
    "events": [{
      "eventName": "Purchase",
      "eventTime": 1798804800,
      "eventId": "order_12345",
      "value": 25.99,
      "currency": "USD",
      "user": { "email": "customer@example.com" }
    }]
  }'

Purchase, Lead, AddToCart, ViewContent, InitiateCheckout, CompleteRegistration, Subscribe, StartTrial and Schedule map to ChatGPT's own event types (Purchase arrives as order_created). Any other name is sent as a custom event. Events go in chunks of 1,000, and one malformed event fails its chunk. See Conversions.

#Limits

#Errors you will see

#Endpoints

#Webhook events