Reddit conversion API v3 wants milliseconds
Reddit CAPI v3 events with official OpenAPI envelope, batch and numeric bounds, seven-day age checks and captured request transport. Account permissions, deduplication history and receiver acceptance remain contextual.
Checks include the 1,000-event ceiling, seven-day event age, metadata bounds and product IDs. Custom event names allow UTF-8 text; avoiding standard names is a recommendation.
What this pack matches
Rules
Codes are stable. A finding in CI, MCP, or the playground lands on the same id.
| Field | Required | What it checks | Rule ids | Source |
|---|---|---|---|---|
pixel_id |
required | It is the Reddit Pixel ID, and it travels in the v3 path. Fix: Put the Pixel ID from Events Manager in the path as `/api/v3/pixels/{pixel_id}/conversion_events`. | vendor.reddit-conversions-api.param.pixel_id.missingvendor.reddit-conversions-api.param.pixel_id.empty |
docs |
data |
required | The vendor documents the JSON shape or value type of this field. Applies when {"kind":"json_type","param":"","json_type":"object"}. Native JSON type: object. | vendor.reddit-conversions-api.body.data.missingvendor.reddit-conversions-api.body.data.invalid |
docs |
data.events |
required | The v3 schema requires one to 1,000 events in data.events. Applies when {"kind":"json_type","param":"data","json_type":"object"}. Native JSON type: array. Minimum array items: 1. Maximum array items: 1000. | vendor.reddit-conversions-api.body.data.events.missingvendor.reddit-conversions-api.body.data.events.invalid |
docs |
data.events[] |
optional | The vendor documents the JSON shape or value type of this field. Native JSON type: object. | vendor.reddit-conversions-api.body.data.events[].invalid |
docs |
root |
optional | The published event or batch envelope is a JSON object. Native JSON type: object. | vendor.reddit-conversions-api.body.root.invalid |
docs |
data.test_id |
optional | Optional Events Testing identifier. The schema does not specify a minimum length. Issuance and account mapping are external. Native JSON type: string. | vendor.reddit-conversions-api.body.data.test_id.invalid |
docs |
event_at |
required | Reddit CAPI v3 documents `event_at` as Unix time in milliseconds. A 10-digit value is seconds and lands in 1970. Body scope: data.events[]. Native JSON type: integer. Fix: Send milliseconds: a JavaScript `Date.now()` is already in the right unit. | vendor.reddit-conversions-api.body.event_at.missingvendor.reddit-conversions-api.body.event_at.emptyvendor.reddit-conversions-api.body.event_at.invalid |
docs |
action_source |
required | v3 makes `action_source` required. Reddit documents `WEBSITE`, `APP`, `PHYSICAL_STORE`, and `OTHER`. Body scope: data.events[]. Native JSON type: string. Fix: Send `WEBSITE`, `APP`, `PHYSICAL_STORE`, or `OTHER`. | vendor.reddit-conversions-api.body.action_source.missingvendor.reddit-conversions-api.body.action_source.emptyvendor.reddit-conversions-api.body.action_source.invalid |
docs |
type.tracking_type |
required | v3 spells standard events in UPPER_SNAKE_CASE. Custom events use `CUSTOM` plus `custom_event_name`. Body scope: data.events[]. Value diagnostic severity: warning. Native JSON type: string. Fix: Send `PURCHASE` or another documented type. For a custom event, send `CUSTOM` and `type.custom_event_name`. | vendor.reddit-conversions-api.body.type.tracking_type.missingvendor.reddit-conversions-api.body.type.tracking_type.emptyvendor.reddit-conversions-api.body.type.tracking_type.invalid |
docs |
click_id |
optional | It is the Reddit click id. Reddit documents it as a match key and reads it from `event_source_url` when the field itself is omitted. Body scope: data.events[]. Native JSON type: string. Fix: Send the `rdt_cid` click id in `click_id`, or put it on `event_source_url`. | vendor.reddit-conversions-api.body.click_id.emptyvendor.reddit-conversions-api.body.click_id.invalid |
docs |
event_source_url |
optional | Reddit documents `event_source_url` as recommended on `WEBSITE` events so the domain can be extracted. Body scope: data.events[]. Native JSON type: string. Fix: Send the absolute page URL in `event_source_url`. | vendor.reddit-conversions-api.body.event_source_url.emptyvendor.reddit-conversions-api.body.event_source_url.invalid |
docs |
type.custom_event_name |
optional | It is the custom event name. Reddit documents it as required when `tracking_type` is `CUSTOM`, any UTF-8 character up to 64 characters including spaces. Body scope: data.events[]. Native JSON type: string. Maximum decoded characters: 64. Fix: Set `type.custom_event_name` to a name that is not a standard tracking type, at most 64 characters. | vendor.reddit-conversions-api.body.type.custom_event_name.emptyvendor.reddit-conversions-api.body.type.custom_event_name.invalid |
docs |
metadata.currency |
optional | It is an ISO 4217 currency code. Body scope: data.events[]. Fix: Use the three-letter code, such as `USD`. | vendor.reddit-conversions-api.body.metadata.currency.emptyvendor.reddit-conversions-api.body.metadata.currency.invalid |
docs |
metadata.value |
optional | It is the conversion value. Reddit documents `value` as strongly recommended on revenue events. Body scope: data.events[]. Native JSON type: number. Minimum numeric value: 0. Fix: Set `metadata.value` to the order total on `PURCHASE`. | vendor.reddit-conversions-api.body.metadata.value.invalid |
docs |
metadata.conversion_id |
optional | It is the id Reddit uses to deduplicate Pixel and CAPI events. Reddit strongly recommends it when both fire. Body scope: data.events[]. Native JSON type: string. Fix: Send the same `conversion_id` the Pixel sent. | vendor.reddit-conversions-api.body.metadata.conversion_id.emptyvendor.reddit-conversions-api.body.metadata.conversion_id.invalid |
docs |
metadata.item_count |
optional | It is the number of items in the conversion. Reddit documents `item_count` as strongly recommended on revenue events, and says product `quantity` is not a replacement. Body scope: data.events[]. Native JSON type: integer. Minimum numeric value: 0. Fix: Set `metadata.item_count` to the order item count, such as `2`. | vendor.reddit-conversions-api.body.metadata.item_count.emptyvendor.reddit-conversions-api.body.metadata.item_count.invalid |
docs |
metadata.products[].id |
optional | It is the product id on a metadata products row. Reddit documents `id` on each product object. Body scope: data.events[]. Native JSON type: string. Fix: Set `metadata.products[].id` to the SKU or catalog id, or drop the empty pair. | vendor.reddit-conversions-api.body.metadata.products[].id.emptyvendor.reddit-conversions-api.body.metadata.products[].id.invalid |
docs |
metadata.products[].name |
optional | It is the product name on a metadata products row. Reddit documents `name` on each product object. Body scope: data.events[]. Native JSON type: string. Fix: Set `metadata.products[].name` to the product name, or drop the empty pair. | vendor.reddit-conversions-api.body.metadata.products[].name.emptyvendor.reddit-conversions-api.body.metadata.products[].name.invalid |
docs |
metadata.products[].category |
optional | It is the product category on a metadata products row. Reddit documents `category` on each product object. Body scope: data.events[]. Native JSON type: string. Fix: Set `metadata.products[].category` to the category, or drop the empty pair. | vendor.reddit-conversions-api.body.metadata.products[].category.emptyvendor.reddit-conversions-api.body.metadata.products[].category.invalid |
docs |
metadata.products[].quantity |
optional | It is the quantity of that product. Reddit documents `quantity` on each product object. It is not a replacement for `metadata.item_count`. Body scope: data.events[]. Native JSON type: integer. Minimum numeric value: 0. Fix: Send `metadata.products[].quantity` as a whole number, such as `2`. | vendor.reddit-conversions-api.body.metadata.products[].quantity.emptyvendor.reddit-conversions-api.body.metadata.products[].quantity.invalid |
docs |
metadata.products[].item_price |
optional | It is the unit price of that product. Reddit documents `item_price` on each product object. It is not a replacement for `metadata.value`. Body scope: data.events[]. Native JSON type: number. Minimum numeric value: 0. Fix: Send `metadata.products[].item_price` as a number, such as `9.99`. Put the order total in `metadata.value`. | vendor.reddit-conversions-api.body.metadata.products[].item_price.invalid |
docs |
user.email |
optional | It is the visitor email. Reddit accepts it unhashed or as SHA-256 hex. Body scope: data.events[]. Native JSON type: string. Fix: Send a canonical email, or the SHA-256 hex digest. | vendor.reddit-conversions-api.body.user.email.emptyvendor.reddit-conversions-api.body.user.email.invalid |
docs |
user.phone_number |
optional | It is the visitor phone number. Reddit accepts it unhashed or as SHA-256 hex. Body scope: data.events[]. Value diagnostic severity: warning. Native JSON type: string. | vendor.reddit-conversions-api.body.user.phone_number.emptyvendor.reddit-conversions-api.body.user.phone_number.invalid |
docs |
user.uuid |
optional | It is the Reddit UUID match key. Reddit documents it for session-based deduplication against the Pixel. Body scope: data.events[]. Native JSON type: string. | vendor.reddit-conversions-api.body.user.uuid.emptyvendor.reddit-conversions-api.body.user.uuid.invalid |
docs |
user.external_id |
optional | It is an advertiser-assigned identifier. Reddit documents it as a match key. Body scope: data.events[]. Native JSON type: string. | vendor.reddit-conversions-api.body.user.external_id.emptyvendor.reddit-conversions-api.body.user.external_id.invalid |
docs |
user.idfa |
optional | It is the iOS advertising id. Reddit documents it as a match key. Body scope: data.events[]. Value diagnostic severity: warning. Native JSON type: string. | vendor.reddit-conversions-api.body.user.idfa.emptyvendor.reddit-conversions-api.body.user.idfa.invalid |
docs |
user.aaid |
optional | It is the Android advertising id. Reddit documents it as a match key. Body scope: data.events[]. Value diagnostic severity: warning. Native JSON type: string. | vendor.reddit-conversions-api.body.user.aaid.emptyvendor.reddit-conversions-api.body.user.aaid.invalid |
docs |
user.ip_address |
optional | It is the visitor IP address. Reddit accepts it unhashed. Body scope: data.events[]. Native JSON type: string. Fix: Send the browser's public IP, not a digest. | vendor.reddit-conversions-api.body.user.ip_address.emptyvendor.reddit-conversions-api.body.user.ip_address.invalid |
docs |
user.user_agent |
optional | It is the visitor user agent. Reddit accepts it unhashed. Body scope: data.events[]. Native JSON type: string. Fix: Send the browser's user agent string, not a digest. | vendor.reddit-conversions-api.body.user.user_agent.emptyvendor.reddit-conversions-api.body.user.user_agent.invalid |
docs |
user.screen_dimensions.width |
optional | It is the display width. Reddit documents `user.screen_dimensions.width` as a match-key field. Body scope: data.events[]. Native JSON type: integer. Minimum numeric value: 0. Maximum numeric value: 32767. Fix: Send `user.screen_dimensions.width` as an integer pixel count. | vendor.reddit-conversions-api.body.user.screen_dimensions.width.emptyvendor.reddit-conversions-api.body.user.screen_dimensions.width.invalid |
docs |
user.screen_dimensions.height |
optional | It is the display height. Reddit documents `user.screen_dimensions.height` as a match-key field. Body scope: data.events[]. Native JSON type: integer. Minimum numeric value: 0. Maximum numeric value: 32767. Fix: Send `user.screen_dimensions.height` as an integer pixel count. | vendor.reddit-conversions-api.body.user.screen_dimensions.height.emptyvendor.reddit-conversions-api.body.user.screen_dimensions.height.invalid |
docs |
user.data_processing_options.modes[] |
optional | It is the Limited Data Use mode. Reddit documents `modes` as the fixed value `LDU`. Body scope: data.events[]. Native JSON type: string. Fix: Send `user.data_processing_options.modes` as `["LDU"]`. | vendor.reddit-conversions-api.body.user.data_processing_options.modes[].emptyvendor.reddit-conversions-api.body.user.data_processing_options.modes[].invalid |
docs |
user.data_processing_options.country |
optional | It is the country for Limited Data Use. Reddit documents country as required when LDU is set. Body scope: data.events[]. Native JSON type: string. Fix: Send `user.data_processing_options.country` when `modes` includes `LDU`. | vendor.reddit-conversions-api.body.user.data_processing_options.country.emptyvendor.reddit-conversions-api.body.user.data_processing_options.country.invalid |
docs |
user.data_processing_options.region |
optional | It is the region for Limited Data Use. Reddit documents region as optional when LDU is set. Body scope: data.events[]. Native JSON type: string. Fix: Send `user.data_processing_options.region`, or omit it. | vendor.reddit-conversions-api.body.user.data_processing_options.region.emptyvendor.reddit-conversions-api.body.user.data_processing_options.region.invalid |
docs |
root |
optional | Each event is a JSON object, rather than a scalar or list. Body scope: data.events[]. Native JSON type: object. | vendor.reddit-conversions-api.body.root.invalid |
docs |
type |
optional | The vendor documents the JSON shape or value type of this field. Body scope: data.events[]. Native JSON type: object. | vendor.reddit-conversions-api.body.type.invalid |
docs |
metadata |
optional | The vendor documents the JSON shape or value type of this field. Body scope: data.events[]. Native JSON type: object. | vendor.reddit-conversions-api.body.metadata.invalid |
docs |
user |
optional | The vendor documents the JSON shape or value type of this field. Body scope: data.events[]. Native JSON type: object. | vendor.reddit-conversions-api.body.user.invalid |
docs |
user.screen_dimensions |
optional | The vendor documents the JSON shape or value type of this field. Body scope: data.events[]. Native JSON type: object. | vendor.reddit-conversions-api.body.user.screen_dimensions.invalid |
docs |
user.data_processing_options |
optional | The vendor documents the JSON shape or value type of this field. Body scope: data.events[]. Native JSON type: object. | vendor.reddit-conversions-api.body.user.data_processing_options.invalid |
docs |
metadata.products |
optional | The vendor documents the JSON shape or value type of this field. Body scope: data.events[]. Native JSON type: array. | vendor.reddit-conversions-api.body.metadata.products.invalid |
docs |
metadata.products[] |
optional | The vendor documents the JSON shape or value type of this field. Body scope: data.events[]. Native JSON type: object. | vendor.reddit-conversions-api.body.metadata.products[].invalid |
docs |
user.data_processing_options.modes |
optional | The vendor documents the JSON shape or value type of this field. Body scope: data.events[]. Native JSON type: array. | vendor.reddit-conversions-api.body.user.data_processing_options.modes.invalid |
docs |
referrer_url |
optional | Optional absolute referring-page URL from the v3 schema. Body scope: data.events[]. Native JSON type: string. | vendor.reddit-conversions-api.body.referrer_url.emptyvendor.reddit-conversions-api.body.referrer_url.invalid |
docs |
metadata.order_id |
optional | Optional advertiser order identifier. Non-string JSON is a type error; the separate truncation rule supplies length advice. Body scope: data.events[]. Native JSON type: string. | vendor.reddit-conversions-api.body.metadata.order_id.invalid |
docs |
body.hashed_plaintext_field |
required | This field looks like a SHA-256 digest, but Reddit documents `user.ip_address` and `user.user_agent` as unhashed match keys. Body scope: data.events[]. Fix: Send the raw IP address or user agent. Hashing it makes the event unmatchable. | vendor.reddit-conversions-api.body.hashed_plaintext_field |
docs |
body.match_key_required |
recommended | The event has no match key. Reddit documents match keys as recommended on each conversion so the event can be matched to a Reddit user. Body scope: data.events[]. Fix: Send `click_id`, hashed or raw `user.email`, `user.phone_number`, `user.uuid`, `user.external_id`, `user.ip_address`, `user.idfa`, or `user.aaid`. | vendor.reddit-conversions-api.body.match_key_required |
docs |
body.website_requires_source_url |
recommended | A `WEBSITE` event has no `event_source_url`. Reddit documents it as recommended so the domain can be extracted. Body scope: data.events[]. Fix: Send the absolute page URL in `event_source_url`. | vendor.reddit-conversions-api.body.website_requires_source_url |
docs |
body.custom_requires_name |
required | A `CUSTOM` event has no `custom_event_name`. Reddit documents that field as the custom event's name. Body scope: data.events[]. Fix: Set `type.custom_event_name` to a name that is not a standard tracking type. | vendor.reddit-conversions-api.body.custom_requires_name |
docs |
body.purchase_requires_value |
recommended | A `PURCHASE` event has no `metadata.value`. Reddit documents value as strongly recommended on revenue events. Body scope: data.events[]. Fix: Set `metadata.value` to the order total. | vendor.reddit-conversions-api.body.purchase_requires_value |
docs |
body.ldu_requires_country |
required | Limited Data Use is enabled but `user.data_processing_options.country` is missing. Reddit documents country as required when `modes` is `LDU`. Body scope: data.events[]. Fix: Send `user.data_processing_options.country` with `modes: ["LDU"]`. | vendor.reddit-conversions-api.body.ldu_requires_country |
docs |
body.custom_name_reserved |
recommended | Reddit recommends that custom event names differ from standard event names. Names remain case-sensitive. Body scope: data.events[]. | vendor.reddit-conversions-api.body.custom_name_reserved |
docs |
body.placeholder_advertising_id |
recommended | Reddit accepts placeholder mobile advertising IDs but reports them as invalid match signals. Body scope: data.events[]. | vendor.reddit-conversions-api.body.placeholder_advertising_id |
docs |
body.event_age |
required | Reddit requires conversion events within seven days of occurrence. The seven-day boundary is inclusive. Body scope: data.events[]. | vendor.reddit-conversions-api.body.event_age |
docs |
body.order_id_truncated |
recommended | Reddit truncates order identifiers longer than 100 characters. Body scope: data.events[]. | vendor.reddit-conversions-api.body.order_id_truncated |
docs |
root |
optional | Product object supplies the presence guard. Body scope: data.events[].metadata.products[]. | docs | |
id |
required | The official schema requires an ID on each submitted product object. Existing parent contracts retain type and nonempty checks. Body scope: data.events[].metadata.products[]. Applies when {"kind":"json_type","param":"","json_type":"object"}. | vendor.reddit-conversions-api.body.id.missing |
docs |
method |
required | The official v3 conversion operation uses POST. Complete HTTP capture contract. Native JSON type: string. | vendor.reddit-conversions-api.http.method.missingvendor.reddit-conversions-api.http.method.emptyvendor.reddit-conversions-api.http.method.invalid |
docs |
content_type |
required | The official operation declares an application/json request entity. Complete HTTP capture contract. Presence diagnostic severity: error. Native JSON type: string. | vendor.reddit-conversions-api.http.content_type.missingvendor.reddit-conversions-api.http.content_type.emptyvendor.reddit-conversions-api.http.content_type.invalid |
docs |
headers.authorization |
required | The OAuth2 operation requires a Bearer credential with adsconversions scope. The opaque token is not verified locally. Complete HTTP capture contract. Presence diagnostic severity: error. Native JSON type: string. | vendor.reddit-conversions-api.http.headers.authorization.missingvendor.reddit-conversions-api.http.headers.authorization.emptyvendor.reddit-conversions-api.http.headers.authorization.invalid |
docs |
body_encoding |
required | The operation requires a JSON request entity. Unsupported encodings and unavailable captures stay unverified. Complete HTTP capture contract. Applies when {"kind":"all","conditions":[{"kind":"not","condition":{"kind":"value_in","param":"body_encoding","values":["unsupported"]}},{"kind":"any","conditions":[{"kind":"value_in","param":"body_encoding","values":["none"]},{"kind":"value_in","param":"content_type","values":["application/json"]}]}]}. Presence diagnostic severity: error. | vendor.reddit-conversions-api.http.body_encoding.missingvendor.reddit-conversions-api.http.body_encoding.emptyvendor.reddit-conversions-api.http.body_encoding.invalid |
docs |
url |
optional | The published API endpoint uses HTTPS. Transport advice does not certify receiver behavior. Complete HTTP capture contract. Presence diagnostic severity: warning. Native JSON type: string. | vendor.reddit-conversions-api.http.url.emptyvendor.reddit-conversions-api.http.url.invalid |
docs |
Validate a payload
pixellint validate request @request.json --rulepack vendor/reddit-conversions-api
Try this failing payload in the playground. An example with a validation finding.
{
"url": "https://ads-api.reddit.com/api/v3/pixels/synthetic-pixel/conversion_events",
"method": "GET",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer synthetic-token"
},
"body": "{\"data\":{\"events\":[{\"event_at\":1770000000000,\"action_source\":\"WEBSITE\",\"type\":{\"tracking_type\":\"PAGE_VISIT\"},\"event_source_url\":\"https://example.test/thank-you\",\"user\":{\"ip_address\":\"203.0.113.42\"}}]}}"
}
cargo install pixellint
·
npm install pixellint