> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dema.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Ads

> Integrating OpenAI Ads with our platform imports the cost and performance of your ChatGPT ad campaigns, enhancing marketing analysis and insights.

export const AdConnectorSteps = ({platform, brand, loginTarget, authButton = "Authorize", authTitle = "Authorize access", authText, accountTitle = "Select ad accounts", accountText, historyTip}) => <Steps>
    <Step title="Navigate to integrations">
      Go to <strong>Settings</strong> on our platform, then click on <strong>Integrations</strong>.
    </Step>
    <Step title={`Connect ${platform}`}>
      Find {platform} in the list of integrations and click <strong>Connect</strong> on that row.
    </Step>
    <Step title={authTitle}>
      {authText ?? <>
          Log in to {loginTarget} and click <strong>{authButton}</strong> to grant the necessary permissions. Once authorized, we'll receive your OAuth token, allowing us to begin fetching data from your {platform} account.
        </>}
    </Step>
    <Step title={accountTitle}>
      {accountText ?? <>After authorization, select the {brand ?? platform} ad account IDs you want to import data from.</>}
      <Tip>
        {historyTip ?? <>
            <strong>Connect all accounts — including inactive ones</strong> — We automatically fetch your history (by default back to <strong>January 1, 2023</strong>). For accurate forecasting, modeling, and cohort analytics, we rely on at least two years of data, so connect any old or inactive accounts too — the more history, the better our models perform.
          </>}
      </Tip>
    </Step>
  </Steps>;

### Supported data types

<CardGroup cols={2}>
  <Card title="Marketing cost" icon="dollar-sign">
    Ad spend and performance metrics
  </Card>

  <Card title="Product cost" icon="tags">
    Product-level advertising costs
  </Card>
</CardGroup>

## Prerequisites

* Access to your [OpenAI Ads Manager](https://ads.openai.com) account
* An Ads Manager API key for the ad account you want to import

## Step-by-step integration guide

<AdConnectorSteps platform="OpenAI Ads" authTitle="Provide your API key" authText={<>Unlike the OAuth-based ad connectors, OpenAI Ads connects with an API key. In OpenAI Ads Manager, go to <strong>Settings</strong> → <strong>General</strong> → <strong>API keys</strong>, create a key and enter it in the connection form. If your merchant has more than one storefront, pick the storefront this connection belongs to from the <strong>Storefront</strong> dropdown in the same form.</>} accountTitle="Choose whether to import product costs" accountText={<>Each OpenAI Ads API key belongs to exactly one ad account, which we detect from the key when you click <strong>Connect</strong>. Leave <strong>Import product costs</strong> checked (the default) to also import spend per product from your product-feed campaigns.</>} historyTip={<>We automatically fetch your history back to <strong>August 31, 2026</strong>.</>} />

### Data collected

This integration fetches the following data from your OpenAI Ads account:

* Account information
* Currency and timezone
* Date of data
* Campaign ID, name, status and daily budget
* Ad group ID and name (shown as ad set)
* Ad ID and name
* Ad title and copy (shown as creative headline and body)
* Channel (`chatgpt`) and channel group (`ai_paid`) — assigned automatically
* Country
* Spend, clicks, impressions, conversions, and attributed sales (conversion value)
* Spend, clicks, and impressions per product, matched on the item ID from your product feed

<Note>
  Product costs only exist for **product-feed campaigns**, and are only imported when **Import product costs** is enabled. OpenAI doesn't report conversions or country per product, so product costs have neither.
</Note>

### Processing

* **Currency:** Costs are imported in the ad account's currency and converted to your merchant currency.
* **Date and timezone:** Costs are dated in the ad account's timezone. Today's numbers are preliminary and are not imported, so costs show up the day after they occur.
* **Country:** Spend, clicks and impressions come from OpenAI's country breakdown. Conversions and attributed sales are split across countries in proportion to each country's share of spend.
* **Attribution:** By default, conversions use a **7-day click and 1-day view** window, dated by when the ad was clicked or viewed.

<Warning>
  **Country breakdown and product costs need segmented insights on your OpenAI ad account.** Without it, product costs are skipped. If your storefront is limited to specific countries, **no costs are imported at all**; otherwise costs are imported with an unknown country. Ask your OpenAI contact to enable segmented insights, or contact your Customer Success Manager.
</Warning>

## Multiple storefronts

Each storefront can have one OpenAI Ads connection, and each API key covers one ad account.

* On merchants with a single storefront, the connection is attached to that storefront automatically and the storefront picker is not shown.
* On merchants with multiple storefronts, the connect form asks you to pick which storefront the connection belongs to.
* To connect OpenAI Ads to an additional storefront later, open **Settings** → **Integrations**, click **OpenAI Ads**, then use **Add** to run the connect flow again with that storefront's API key.

Reconnecting an existing connection only asks for a new API key. Disconnecting removes the stored key, so revoke keys you no longer use in OpenAI Ads Manager.

## Data refresh

<CardGroup cols={2}>
  <Card title="Initial import" icon="download">
    On the first fetch, we import historical data going back to **2026-08-31**.
  </Card>

  <Card title="Ongoing updates" icon="rotate">
    Subsequent updates re-fetch the **last 7 days**, so conversions attributed after the click are picked up.
  </Card>
</CardGroup>

## Finalizing integration

Once your API key is set up, our system automatically begins fetching your OpenAI Ads data. You can then view and analyze this data on our platform to gain insights into your advertising performance.

## Troubleshooting and support

If you encounter any issues during the integration process or have questions regarding your data, please contact our support team for assistance. Common connection errors:

<AccordionGroup>
  <Accordion title="The API key was rejected" icon="key">
    Check that you copied the whole key and that it hasn't been revoked in OpenAI Ads Manager, then connect again.
  </Accordion>

  <Accordion title="The API key has no ad account" icon="circle-exclamation">
    Create the key from inside the ad account you want to import, under **Settings** → **General** → **API keys**.
  </Accordion>

  <Accordion title="The API key is scoped to a different ad account" icon="right-left">
    On reconnect, use a key from the ad account that is already connected. To switch to a different ad account, contact support.
  </Accordion>

  <Accordion title="No costs, or costs with an unknown country" icon="earth-europe">
    Segmented insights are probably not enabled on your OpenAI ad account. See the warning under [Processing](#processing).
  </Accordion>
</AccordionGroup>

## Additional resources

For more information on managing your OpenAI Ads account, visit [OpenAI Ads Manager](https://ads.openai.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.