ConversionEvent

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/reddit/json-schema/reddit-components-schema-pixel-conversion-event-schema.json",
  "title": "ConversionEvent",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/reddit-ads-api-openapi.yml#/components/schemas/components_schema_pixel_conversion_event",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "event_at",
    "action_source",
    "type"
  ],
  "properties": {
    "click_id": {
      "type": "string",
      "description": "<span id='click-id-field'></span>The Reddit-generated ID associated with an ad click. Recommended for all conversion events. Learn how to [implement click ID persistence](https://ads-api.reddit.com/docs/v3/capi-click-id-persistence)."
    },
    "event_at": {
      "type": "integer",
      "description": "When the conversion event occurred (Unix epoch in milliseconds).",
      "format": "int64"
    },
    "action_source": {
      "type": "string",
      "title": "ConversionEventActionSource",
      "description": "<span id=\"action-source-field\"></span>The channel where the conversion happened. Used for [source-level conversion metrics](https://business.reddithelp.com/s/article/Custom-Columns#supported-metrics) in reporting.\n",
      "enum": [
        "WEBSITE",
        "APP",
        "OTHER",
        "PHYSICAL_STORE"
      ]
    },
    "event_source_url": {
      "type": "string",
      "description": "The URL where the conversion event occurred. Used to parse a domain for [event details](https://business.reddithelp.com/s/article/Events-Manager#view-event-details). Applies only to [`WEBSITE` events](https://business.reddithelp.com/s/article/Conversions-API#measure-impact-across-channels).\n> **Tip:** When the click ID is appended, that identifier is extracted to improve coverage when the `click_id` parameter isn’t provided.\n",
      "format": "url"
    },
    "referrer_url": {
      "type": "string",
      "description": "The URL of the page that referred the user to the conversion page.\n",
      "format": "url"
    },
    "type": {
      "type": "object",
      "description": "Classifies the conversion event. Used for aggregating data in reporting. At least `tracking_type` must be defined.",
      "additionalProperties": false,
      "properties": {
        "custom_event_name": {
          "type": "string",
          "description": "A custom event name to pass when `tracking_type` is set to `CUSTOM`. \n\nThis free-form and case-sensitive string may use any UTF-8 character and can have up to 64 characters, including spaces. For example, `Promotion Event` and `PromotionEvent` will be considered two distinct events. \n\nWe recommend setting this to a value that doesn't match a standard event.\n"
        },
        "tracking_type": {
          "$ref": "#/$defs/standard_tracking_type"
        }
      }
    },
    "metadata": {
      "type": "object",
      "description": "The conversion event's [metadata](https://business.reddithelp.com/s/article/about-event-metadata).",
      "additionalProperties": false,
      "properties": {
        "conversion_id": {
          "type": "string",
          "description": "The unique ID corresponding to a distinct conversion event. This is used for [deduplication](https://business.reddithelp.com/s/article/event-deduplication) and prevents the same conversion event from being processed more than once when sent multiple times."
        },
        "order_id": {
          "type": "string",
          "maxLength": 100,
          "description": "The advertiser-assigned order identifier for the transaction. Values longer than 100 characters are truncated.\n"
        },
        "currency": {
          "type": "string",
          "description": "The value's currency ([ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)). Only set for revenue-related events."
        },
        "item_count": {
          "type": "integer",
          "description": "The total items in the event. Only set for revenue-related events.",
          "format": "int32",
          "minimum": 0
        },
        "value": {
          "type": "number",
          "description": "The transaction's value in the base unit of the currency. For example, dollars (USD), euros (EUR), pesos (MXN), rupees (INR), and bitcoin (BTC). Only set for revenue-related events.",
          "format": "double",
          "minimum": 0
        },
        "products": {
          "type": "array",
          "description": "An array of the event's products. > **Important:** `quantity` and `item_price` are not replacements for `item_count` and `value`, which are used for optimization and strongly recommended for revenue-related events.\n",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id"
            ],
            "properties": {
              "category": {
                "type": "string",
                "description": "The category the product is in, such as the label from Google's product taxonomy."
              },
              "id": {
                "type": "string",
                "description": "The ID representing the product in your catalog."
              },
              "name": {
                "type": "string",
                "description": "The product's name."
              },
              "quantity": {
                "type": "integer",
                "minimum": 0,
                "description": "The number of units of this product."
              },
              "item_price": {
                "type": "number",
                "minimum": 0,
                "description": "The unit price."
              }
            }
          }
        }
      }
    },
    "user": {
      "type": "object",
      "additionalProperties": false,
      "description": "The identifying user parameters associated with the conversion event. Learn more about [match keys](https://business.reddithelp.com/s/article/about-match-keys).",
      "properties": {
        "email": {
          "type": "string",
          "description": "The user's email address."
        },
        "external_id": {
          "type": "string",
          "description": "An advertiser-assigned persistent identifier for the user."
        },
        "ip_address": {
          "type": "string",
          "description": "The user's IP address."
        },
        "phone_number": {
          "type": "string",
          "description": "The user's phone number ([E.164](https://www.itu.int/rec/T-REC-E.164-201011-I/en))."
        },
        "user_agent": {
          "type": "string",
          "description": "The user agent of the user's browser."
        },
        "aaid": {
          "type": "string",
          "description": "The Android Advertising ID (AAID) of the user's Android device."
        },
        "idfa": {
          "type": "string",
          "description": "The Identifier for Advertisers (IDFA) of the user's iOS device."
        },
        "uuid": {
          "type": "string",
          "description": "The value of the first-party Pixel `_rdt_uuid` cookie on your domain. Provide it as-is (`{timestamp}.{uuid}` format) or the UUID alone."
        },
        "data_processing_options": {
          "type": "object",
          "description": "A structure of data processing options to specify the event's processing type.",
          "additionalProperties": false,
          "properties": {
            "country": {
              "type": "string",
              "description": "The user's country code ([ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#search/code/))."
            },
            "region": {
              "type": "string",
              "description": "The user's region code, provided as the [ISO 3166-2](https://www.iso.org/iso-3166-country-codes.html) subdivision code or the subdivision code without the country prefix (e.g., `CA`)."
            },
            "modes": {
              "type": "array",
              "description": "An array of data processing modes.",
              "items": {
                "type": "string",
                "x-enumDescriptions": {
                  "LDU": "Limited Data Use; the only supported mode."
                },
                "enum": [
                  "LDU"
                ]
              }
            }
          }
        },
        "screen_dimensions": {
          "type": "object",
          "description": "The user's screen dimensions.",
          "additionalProperties": false,
          "properties": {
            "height": {
              "type": "integer",
              "description": "The user's screen height (pixels).",
              "format": "int16",
              "minimum": 0,
              "maximum": 32767
            },
            "width": {
              "type": "integer",
              "description": "The user's screen width (pixels).",
              "format": "int16",
              "minimum": 0,
              "maximum": 32767
            }
          }
        }
      }
    }
  },
  "$defs": {
    "standard_tracking_type": {
      "type": "string",
      "description": "The [conversion event type](https://business.reddithelp.com/s/article/supported-conversion-events).",
      "x-enumDescriptions": {
        "CUSTOM": "A custom conversion event identified by its event name."
      },
      "enum": [
        "PAGE_VISIT",
        "VIEW_CONTENT",
        "SEARCH",
        "ADD_TO_CART",
        "ADD_TO_WISHLIST",
        "PURCHASE",
        "LEAD",
        "SIGN_UP",
        "CUSTOM"
      ]
    }
  }
}