pixellint

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

Hosts
ads-api.reddit.com
Paths
Full path expression: /api/v3/pixels/[^/]+/conversion_events
Vendor docs
ads-api.reddit.com/docs/v3/guides/programs/capi/direct-integration

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.missing
vendor.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.missing
vendor.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.missing
vendor.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.missing
vendor.reddit-conversions-api.body.event_at.empty
vendor.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.missing
vendor.reddit-conversions-api.body.action_source.empty
vendor.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.missing
vendor.reddit-conversions-api.body.type.tracking_type.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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[].empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.missing
vendor.reddit-conversions-api.http.method.empty
vendor.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.missing
vendor.reddit-conversions-api.http.content_type.empty
vendor.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.missing
vendor.reddit-conversions-api.http.headers.authorization.empty
vendor.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.missing
vendor.reddit-conversions-api.http.body_encoding.empty
vendor.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.empty
vendor.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