{ "$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": "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": "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" ] } } }