Reddit Conversion Events: Every Field in the v3 Payload

Reddit conversion events travel through a single POST to https://ads-api.reddit.com/api/v3/pixels/<pixel_id>/conversion_events, and the whole event lives inside one entry of the events array. The schema is small - a timestamp, an action source, a type, optional metadata and user objects - but each field carries documented rules, and the payloads that get rejected are almost always the ones that ignore one of them.

The Events Array and Its Required Frame

Reddit's reference sample shows the frame: a top-level data object holding an events array, where each element is one conversion. The request authenticates with the conversion access token as a bearer header and returns a confirmation about successfully processed events. Batching is capped at 1,000 events per call, with platform ceilings of 1,000 requests and 10,000 events per second - far above a single funnel, relevant when a tracker's backlog drains after downtime. Every event must also respect the freshness rule: event_at may not be older than seven days at sending time.

event_at, action_source, and event_source_url

event_at is the conversion timestamp - the field the seven-day window applies to, so a delayed postback is recoverable within the week but not after. action_source says where the conversion happened: WEBSITE, PHYSICAL_STORE, or an app source. The choice is not cosmetic: Reddit states that PHYSICAL_STORE events should not carry device identifiers - no click ID, UUID, or mobile advertising IDs - because the store has no device to identify.

event_source_url is recommended for WEBSITE events: Reddit extracts the domain for reporting, and - a useful fallback - a click ID present in the URL is picked up when the dedicated click_id field is missing.

type and tracking_type: Naming the Conversion

Inside sits tracking_type, and Reddit's sample shows values such as PURCHASE, LEAD, and PAGE_VISIT; anything the enum does not cover goes out as CUSTOM with a custom_event_name of up to 64 case-sensitive UTF-8 characters. The dashboard shows only the 20 most recent custom events - a scheme that keeps rotating new names washes older ones out of the UI. Version discipline matters here too: tracking_type was among the fields that changed between CAPI v2 and v3, and sending the same conversions through both versions double-counts them.

metadata and user: Revenue, Identity, Match Keys

The metadata object carries the conversion's business fields - conversion_id, currency, value - and conversion_id is the field Reddit's deduplication prefers: a unique identifier per distinct conversion, sent identically by every channel reporting that conversion. Match keys ride in the user object: ip_address, external_id, hashed email and phone, mobile IDs - the identifiers Reddit matches against real profiles, with IP address and the click ID strongly recommended. Hashing follows strict canonicalization rules; the cross-platform picture is in match keys.

{
  "data": {
    "events": [
      {
        "click_id": "3184742045291813272",
        "event_at": 1790000000000,
        "action_source": "WEBSITE",
        "event_source_url": "https://www.example.com/checkout?rdt_cid=3184742045291813272",
        "type": { "tracking_type": "PURCHASE" },
        "metadata": { "conversion_id": "order-8842", "currency": "USD", "value": 49.9 },
        "user": { "ip_address": "192.0.2.1", "external_id": "7c73f2ae-a433-4d7b-9838-f467da98f48e" }
      }
    ]
  }
}

The payload mirrors Reddit's reference sample: one conversion, all required frames, both identifier families in place - a conversion_id in metadata, the click ID at the event's top level, and the user identifiers in user.

Rules That Silently Break Payloads

Each of these arrives with a documented error or a documented warning; the responses and their fixes are in the error handling guide - Reddit Conversions API errors. The full-integration context, credentials included, lives in Reddit Conversions API setup, and the cluster map is in the complete guide.

Sources