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

# Conversions Config Reference

Conversion **event settings** are account-level definitions of the actions you count as conversions — a lead submitted, a pricing page viewed, an order placed. They live at the top level of your OpenAI Ads config as `[[conversions]]` entries, and campaigns reference them by ID via [`conversion_event_ids`](/docs/config/openai/campaigns).

<Note>
  **Create-only.** The OpenAI Ads API can create and list conversion event settings, but has **no update, archive, or delete endpoint** for them. So Adjar can create a declared conversion and reference it, but editing or removing one is done in the OpenAI Ads dashboard. `adjar plan` **errors** if you change a field on an existing (id-bearing) conversion rather than silently ignoring it — drop the `id` to create a new one, or make the edit in the dashboard.
</Note>

## Full Example

```toml theme={null}
[[conversions]]
name = "Contact form submitted"
event_type = "lead_created"
source_ids = [ "cds_6a579f74e7d0819fab11c830d1bccff9" ]

[[conversions]]
name = "Signed up"
event_type = "custom"
custom_event_name = "signed_up"
attribution_window_days = 30
source_ids = [ "cds_6a579f74e7d0819fab11c830d1bccff9" ]
```

## How they connect

```
Conversion source (pixel / CAPI key)   ← provisioned in the dashboard
        │  source_ids
        ▼
[[conversions]] event setting          ← managed here (create + reference)
        │  conversion_event_ids
        ▼
[[campaigns]]                          ← references the event setting by id
```

Create a conversion once (or import it), then reference its ID from any campaign's `conversion_event_ids`. Because conversions are create-only, the usual flow is: declare the conversion, `adjar apply` (which writes its ID back), then add that ID to the campaigns that should count it.

## `[[conversions]]` Fields

<ParamField path="name" type="string" required>
  The conversion's display name, 3–1000 characters.

  ```toml theme={null}
  name = "Contact form submitted"
  ```
</ParamField>

<ParamField path="event_type" type="string" required>
  The event this conversion tracks — one of the standard types, or `"custom"`.

  | Standard values                                                                                                                                                                                                                 |
  | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `app_installed`, `app_opened`, `appointment_scheduled`, `checkout_started`, `contents_viewed`, `items_added`, `lead_created`, `order_created`, `page_viewed`, `registration_completed`, `subscription_created`, `trial_started` |

  ```toml theme={null}
  event_type = "lead_created"
  ```

  Use `"custom"` for an action the standard taxonomy doesn't cover, and set `custom_event_name`.
</ParamField>

<ParamField path="custom_event_name" type="string">
  Required when `event_type` is `"custom"`. Lowercase letters, numbers, underscores, or dashes; 1–64 characters; and not one of the built-in event names.

  ```toml theme={null}
  event_type = "custom"
  custom_event_name = "signed_up"
  ```
</ParamField>

<ParamField path="attribution_window_days" type="integer" default="30">
  The attribution window, in days. The API currently uses `30`; omit to take the default.

  ```toml theme={null}
  attribution_window_days = 30
  ```
</ParamField>

<ParamField path="source_ids" type="array of strings" required>
  Exactly one conversion **source** ID — a `cds_…` pixel or Conversions API key. Sources are provisioned in the OpenAI Ads dashboard (pixel install or CAPI setup); Adjar passes the ID through as an opaque reference and does not manage sources.

  ```toml theme={null}
  source_ids = [ "cds_6a579f74e7d0819fab11c830d1bccff9" ]
  ```
</ParamField>

***

## Related Pages

* [Campaigns](/docs/config/openai/campaigns) — `conversion_event_ids` references these settings by ID
* [Account Root](/docs/config/openai/account) — how `[[conversions]]` are imported via `openai.toml`
* [OpenAI Ads API access](/docs/openai-ads-api-access) — producing the `openai.json` credentials file