OpenAI Ads

What's Supported

Connect an Ad Account

Create the key in ChatGPT Ads Manager under Settings, then either connect from the Zernio dashboard (Connections tab) or via API:

const { data: account } = await zernio.connect.connectOpenAIAdsCredentials({
  body: {
    apiKey: "YOUR_OPENAI_ADS_API_KEY",
    profileId: "PROFILE_ID",
  },
});
console.log(`Connected: ${account.accountId}`);

The key is validated against OpenAI before anything is stored. Re-posting a rotated key for the same ad account updates the connection in place. For sending your own customers a connect link, the endpoint also accepts the x-connect-token header flow used by the other connect endpoints.

Create a Campaign

Chat card ads have a title (3 to 50 characters), a body (up to 100 characters), an image, and a destination URL. adAccountId is the OpenAI ad account id (acct_...) returned when you connect. OpenAI budgets are lifetime-only, so budgetType must be "lifetime" and endDate is required.

const { data: ad } = await zernio.ads.createStandaloneAd({ body: {
  accountId: "acc_openaiads_123",
  adAccountId: "acct_abc123",
  name: "Workspace planner launch",
  goal: "traffic",
  budgetAmount: 25,
  budgetType: "lifetime",
  endDate: "2026-08-31",
  headline: "Try the new workspace planner",
  body: "Coordinate tasks, docs, and meetings in one place.",
  imageUrl: "https://cdn.example.com/planner.png",
  linkUrl: "https://example.com/workspace-planner",
  countries: ["US"],
}});

Goals map to OpenAI bidding: traffic bids on clicks, awareness on impressions, conversions on conversion events. The conversions goal requires an active conversion event setting on the ad account; create one with a tracking tag (below) or in OpenAI Ads Manager.

Targeting is location-only. Anything else (ages, genders, interests) returns a validation error rather than being silently dropped. The same applies to bidding: bidStrategy and bidAmount map to OpenAI's max bid (a CPA bid under the conversions goal), and ROAS-based strategies return a validation error since OpenAI has no ROAS bidding.

Manage Ads

Pause, resume and budget changes work like every other ads platform (PUT /v1/ads/{adId}/status, campaign status, budget endpoints).

Conversion Tracking

Create a pixel and a server-side Conversions API key in one call. Pass defaultEventType to also provision the conversion event setting that goal: "conversions" needs:

const { data: tag } = await zernio.trackingtags.createTrackingTag({
  path: { accountId: "ACCOUNT_ID" },
  body: { adAccountId: "acct_abc123", name: "Acme website", defaultEventType: "order_created" },
});

Send server-side conversion events through the shared conversions endpoint. The destination id comes from GET /v1/accounts/{accountId}/conversion-destinations:

await zernio.ads.sendConversions({ body: {
  accountId: "acc_openaiads_123",
  destinationId: "134534000000",
  events: [{
    eventName: "Purchase",
    eventTime: Math.floor(Date.now() / 1000),
    eventId: "order_12345",
    sourceUrl: "https://shop.example.com/checkout/confirmation",
    value: 25.99,
    currency: "USD",
    user: { email: "customer@example.com" },
  }],
}});

Zernio batches to OpenAI's Conversions API (up to 1,000 events per batch), maps Zernio standard events to OpenAI names (Purchase to order_created, Lead to lead_created, AddToCart to items_added, and friends; unmapped names go as custom), hashes email identifiers, and sends monetary amounts in minor units as OpenAI requires. Note OpenAI fails a whole batch if any single event is invalid; Zernio surfaces which batch failed.

Limits Cheat Sheet