Send server-side events to a Reddit pixel through the Conversions API, and how Zernio maps each field.

POST /v1/ads/conversions sends server-side events to a Reddit pixel through Reddit's Conversions API.

Before you start

The connection needs the adsconversions permission (Reconnect if it is missing). Pixels are created in Reddit Ads Manager.

destinationId is the pixel id. List the pixels of every synced ad account with GET /v1/accounts/{accountId}/conversion-destinations:

{
  "platform": "redditads",
  "destinations": [
    { "id": "a2_gu5tcd9ah5se", "name": "Acme website", "status": "active", "adAccountId": "a2_gu5tcd9ah5se" }
  ]
}

Send a conversion event

Send each event with at least one match key, such as the rdt_cid click id or an email.

const { data: sent } = await zernio.conversions.sendConversions({
  body: {
    accountId: '66b2e19d8c3f5a7e9d0b1c2d',
    destinationId: 'a2_gu5tcd9ah5se',
    events: [{
      eventName: 'Purchase',
      eventTime: 1798804800,
      eventId: 'order_12345',
      sourceUrl: 'https://shop.example.com/checkout/confirmation',
      value: 25.99,
      currency: 'USD',
      user: {
        email: 'customer@example.com',
        ipAddress: '203.0.113.7',
        userAgent: 'Mozilla/5.0 ...',
        clickIds: { rdt_cid: '1234567890abcdef' }
      }
    }]
  }
});

console.log(sent.eventsReceived);

Response (200):

{
  "platform": "redditads",
  "eventsReceived": 1,
  "eventsFailed": 0,
  "failures": []
}

How Zernio maps each event

Zernio field	Reddit field	Notes
`eventName`	`type.tracking_type`	`Purchase`, `Lead`, `CompleteRegistration` (as `SIGN_UP`), `AddToCart`, `AddToWishlist`, `ViewContent`, `Search` and `PageView` (as `PAGE_VISIT`) map to Reddit's standard events; any other name is sent as a custom event with the name kept
`eventTime`	`event_at`	Unix seconds. Reddit accepts events up to 7 days old
`eventId`	`metadata.conversion_id`	Deduplicates against the same event fired by the pixel
`value`, `currency`, `items`	`metadata`	`items` become `products` and `item_count`
`user.clickIds.rdt_cid`	`click_id`	The Reddit click id from the landing URL
`user.clickIds.rdt_uuid`	`user.uuid`	The pixel's first-party id (`_rdt_uuid` cookie)
`user.email`, `user.phone`, `user.externalId`	`user`	Hashed with SHA-256 by Zernio: send plain values
`user.ipAddress`, `user.userAgent`	`user`	Sent as is
`actionSource`	`action_source`	`web` (the default) is `WEBSITE`, `app` is `APP`, anything else `OTHER`

How it behaves

Every event needs at least one match key: rdt_cid, rdt_uuid, an email, a phone, an external id, or the IP address together with the user agent.
consent.adUserData: "DENIED" drops the user identifiers, leaving only the click id.
Pass testCode to send the batch with Reddit's test_id, so you can check it in Reddit's Events Manager.
Larger submissions are sent in chunks of 1,000 events.
An event older than 7 days, timed more than an hour in the future (usually a millisecond timestamp) or with no match key is reported in failures[] with code INVALID_EVENT, and the rest still go.
A chunk Reddit rejects lands in failures[] with code REDDIT_REJECTED and Reddit's message.

If it fails

Error	Cause	Fix
`403` with code `reconnect_required`	The connection lacks `adsconversions`	Reconnect Reddit Ads.
`403` with code `insufficient_permissions`	The connected Reddit user has no role on the ad account that owns the pixel	Grant the user a role on that ad account in Reddit Ads Manager.
`401` with code `reconnect_required`	Reddit rejected the token	Reconnect.
`400` with code `invalid_field_value`	`destinationId` is not a Reddit pixel id	Use an `id` from `conversion-destinations`.

Send conversions: every field of the request.
List conversion destinations: the pixel ids destinationId takes.
Create a campaign: campaigns that optimize toward a pixel event.
Read ad analytics: spend, impressions and clicks per ad.

POST /v1/ads/conversions sends server-side events to a Reddit pixel through Reddit's Conversions API.

Before you start

The connection needs the adsconversions permission (Reconnect if it is missing). Pixels are created in Reddit Ads Manager.

destinationId is the pixel id. List the pixels of every synced ad account with GET /v1/accounts/{accountId}/conversion-destinations:

{
  "platform": "redditads",
  "destinations": [
    { "id": "a2_gu5tcd9ah5se", "name": "Acme website", "status": "active", "adAccountId": "a2_gu5tcd9ah5se" }
  ]
}

Send a conversion event

Send each event with at least one match key, such as the rdt_cid click id or an email.

const { data: sent } = await zernio.conversions.sendConversions({
  body: {
    accountId: '66b2e19d8c3f5a7e9d0b1c2d',
    destinationId: 'a2_gu5tcd9ah5se',
    events: [{
      eventName: 'Purchase',
      eventTime: 1798804800,
      eventId: 'order_12345',
      sourceUrl: 'https://shop.example.com/checkout/confirmation',
      value: 25.99,
      currency: 'USD',
      user: {
        email: 'customer@example.com',
        ipAddress: '203.0.113.7',
        userAgent: 'Mozilla/5.0 ...',
        clickIds: { rdt_cid: '1234567890abcdef' }
      }
    }]
  }
});

console.log(sent.eventsReceived);

Response (200):

{
  "platform": "redditads",
  "eventsReceived": 1,
  "eventsFailed": 0,
  "failures": []
}

How Zernio maps each event

Zernio field	Reddit field	Notes
`eventName`	`type.tracking_type`	`Purchase`, `Lead`, `CompleteRegistration` (as `SIGN_UP`), `AddToCart`, `AddToWishlist`, `ViewContent`, `Search` and `PageView` (as `PAGE_VISIT`) map to Reddit's standard events; any other name is sent as a custom event with the name kept
`eventTime`	`event_at`	Unix seconds. Reddit accepts events up to 7 days old
`eventId`	`metadata.conversion_id`	Deduplicates against the same event fired by the pixel
`value`, `currency`, `items`	`metadata`	`items` become `products` and `item_count`
`user.clickIds.rdt_cid`	`click_id`	The Reddit click id from the landing URL
`user.clickIds.rdt_uuid`	`user.uuid`	The pixel's first-party id (`_rdt_uuid` cookie)
`user.email`, `user.phone`, `user.externalId`	`user`	Hashed with SHA-256 by Zernio: send plain values
`user.ipAddress`, `user.userAgent`	`user`	Sent as is
`actionSource`	`action_source`	`web` (the default) is `WEBSITE`, `app` is `APP`, anything else `OTHER`

How it behaves

Every event needs at least one match key: rdt_cid, rdt_uuid, an email, a phone, an external id, or the IP address together with the user agent.
consent.adUserData: "DENIED" drops the user identifiers, leaving only the click id.
Pass testCode to send the batch with Reddit's test_id, so you can check it in Reddit's Events Manager.
Larger submissions are sent in chunks of 1,000 events.
An event older than 7 days, timed more than an hour in the future (usually a millisecond timestamp) or with no match key is reported in failures[] with code INVALID_EVENT, and the rest still go.
A chunk Reddit rejects lands in failures[] with code REDDIT_REJECTED and Reddit's message.

If it fails

Error	Cause	Fix
`403` with code `reconnect_required`	The connection lacks `adsconversions`	Reconnect Reddit Ads.
`403` with code `insufficient_permissions`	The connected Reddit user has no role on the ad account that owns the pixel	Grant the user a role on that ad account in Reddit Ads Manager.
`401` with code `reconnect_required`	Reddit rejected the token	Reconnect.
`400` with code `invalid_field_value`	`destinationId` is not a Reddit pixel id	Use an `id` from `conversion-destinations`.

Send conversions: every field of the request.
List conversion destinations: the pixel ids destinationId takes.
Create a campaign: campaigns that optimize toward a pixel event.
Read ad analytics: spend, impressions and clicks per ad.

Conversions API

Before you start

Send a conversion event

How Zernio maps each event

How it behaves

If it fails

On this page

Conversions API

Before you start

Send a conversion event

How Zernio maps each event

How it behaves

If it fails

On this page