Reddit Conversions API
Server-side event delivery to Reddit's Conversions API v2.0 for enhanced conversion tracking, bypassing browser limitations and improving match quality for ad optimization.
Reddit Conversions API is a server destination in the walkerOS flow:
Sends events server-side to Reddit's Conversions API using raw HTTP (no SDK). Identity fields (`email`, `external_id`, `ip_address`, `user_agent`, `idfa`, `aaid`) are SHA-256 hashed, as mapped, before sending. Events include a stable `event_metadata.conversion_id`, the walkerOS event id.
Installation
npm install @walkeros/collector @walkeros/server-destination-reddit- Integrated
- Bundled
import { startFlow } from '@walkeros/collector';
import destinationReddit from '@walkeros/server-destination-reddit';
await startFlow({
destinations: {
reddit: {
code: destinationReddit,
config: {
settings: {
accessToken: process.env.REDDIT_ACCESS_TOKEN,
pixelId: 'a2_abcdef123456',
},
},
},
},
});
A complete flow.json with this destination:
{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "server"
},
"destinations": {
"reddit": {
"package": "@walkeros/server-destination-reddit",
"config": {
"settings": {
"accessToken": "$secret.REDDIT_ACCESS_TOKEN",
"pixelId": "a2_abcdef123456"
}
}
}
}
}
}
}Configuration
This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.
Settings
| Property | Type | Description | More |
|---|---|---|---|
accessToken | string | Reddit Conversion Access Token for Bearer authentication | |
pixelId | string | Reddit Pixel ID used as the API path parameter | |
action_source | Has no effect: the destination sends no action source to Reddit (accepts WEBSITE, APP, PHYSICAL_STORE) | ||
doNotHash | Array<string> | Array of user fields that should not be hashed | |
test_mode | boolean | Enable test mode by sending test_mode: true in the request body | |
url | string | Custom base URL for the Reddit Conversions API, ending in /; the pixel ID is appended | |
user_data | Record<string, string> | Mapping configuration for user fields | |
ip | any | boolean | Client IP, sent as user.ip_address (hashed). Resolves against { ingest, event }. Default: ["ingest.ip", "event.user.ip"]. false switches it off. A mapped user.ip_address wins. | |
userAgent | any | boolean | Client user agent, sent as user.user_agent (hashed). Resolves against { ingest, event }. Default: ["ingest.userAgent", "event.user.userAgent"]. false switches it off. A mapped user.user_agent wins. |
Mapping
This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
Examples
Add to cart
A product add is sent to Reddit as an AddToCart conversion with value and product details.
{
"name": "product add",
"data": {
"id": "SKU-B2",
"name": "Cool Cap",
"category": "hats",
"price": "42.00",
"quantity": 1
},
"context": {
"shopping": [
"intent",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "user-456"
},
"nested": [],
"consent": {
"functional": true
},
"id": "ev-1700000901",
"trigger": "click",
"entity": "product",
"action": "add",
"timestamp": 1700000901000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "express",
"platform": "server"
}
}{
"name": "AddToCart",
"data": {
"map": {
"event_metadata": {
"map": {
"value_decimal": "data.price",
"currency": {
"value": "EUR"
},
"item_count": {
"value": 1
},
"products": {
"set": [
{
"map": {
"id": "data.id",
"name": "data.name",
"category": {
"key": "data.category",
"value": "uncategorized"
}
}
}
]
}
}
}
}
}
}sendServer("https://ads-api.reddit.com/api/v2.0/conversions/events/a2_abcdef123456", "{\"data\":{\"events\":[{\"event_at\":\"2023-11-14T22:28:21.000Z\",\"event_at_ms\":1700000901000,\"event_type\":{\"tracking_type\":\"AddToCart\"},\"user\":{},\"event_metadata\":{\"conversion_id\":\"ev-1700000901\",\"value_decimal\":\"42.00\",\"currency\":\"EUR\",\"item_count\":1,\"products\":[{\"id\":\"SKU-B2\",\"name\":\"Cool Cap\",\"category\":\"hats\"}]}}]}}", {
"headers": {
"Authorization": "Bearer s3cr3t"
}
})Lead
A form submission is sent to Reddit as a Lead conversion with the SHA-256 hashed email and external id.
{
"name": "form submit",
"data": {
"form": "contact"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"lang": "elb"
},
"custom": {
"completely": "random"
},
"user": {
"id": "user-lead-1",
"email": "lead@example.com"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev-1700000903",
"trigger": "test",
"entity": "form",
"action": "submit",
"timestamp": 1700000903000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "express",
"platform": "server"
}
}{
"name": "Lead",
"data": {
"map": {
"user": {
"map": {
"email": "user.email",
"external_id": "user.id"
}
}
}
}
}sendServer("https://ads-api.reddit.com/api/v2.0/conversions/events/a2_abcdef123456", "{\"data\":{\"events\":[{\"event_at\":\"2023-11-14T22:28:23.000Z\",\"event_at_ms\":1700000903000,\"event_type\":{\"tracking_type\":\"Lead\"},\"user\":{\"email\":\"9fbdefe2837a03c9225be80e741f316f4d174d1732b719b6abb6477efc1ae9d2\",\"external_id\":\"ee818eebb052cf288ffeeb2e09ee35c9946e1a7f53a959cb3ef06d5d4adb78e8\"},\"event_metadata\":{\"conversion_id\":\"ev-1700000903\"}}]}}", {
"headers": {
"Authorization": "Bearer s3cr3t"
}
})Page visit
A page view is sent to Reddit as a PageVisit conversion used for retargeting audiences.
{
"name": "page view",
"data": {
"domain": "www.example.com",
"title": "walkerOS documentation",
"referrer": "https://www.walkeros.io/",
"search": "?foo=bar",
"hash": "#hash",
"id": "/docs/"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"pagegroup": "docs"
},
"custom": {
"completely": "random"
},
"user": {
"id": "user-789"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev-1700000902",
"trigger": "load",
"entity": "page",
"action": "view",
"timestamp": 1700000902000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "express",
"platform": "server"
}
}{
"name": "PageVisit"
}sendServer("https://ads-api.reddit.com/api/v2.0/conversions/events/a2_abcdef123456", "{\"data\":{\"events\":[{\"event_at\":\"2023-11-14T22:28:22.000Z\",\"event_at_ms\":1700000902000,\"event_type\":{\"tracking_type\":\"PageVisit\"},\"user\":{},\"event_metadata\":{\"conversion_id\":\"ev-1700000902\"}}]}}", {
"headers": {
"Authorization": "Bearer s3cr3t"
}
})Purchase
A completed order is sent to the Reddit Conversions API as a Purchase event with value, currency, and items.
{
"name": "order complete",
"data": {
"id": "ORD-300",
"value": 249.99,
"currency": "EUR"
},
"context": {
"shopping": [
"complete",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "user-123",
"device": "device-456"
},
"nested": [
{
"entity": "product",
"data": {
"id": "SKU-A1",
"name": "Everyday Ruck Snack",
"category": "bags",
"price": "129.99",
"quantity": 2
}
}
],
"consent": {
"functional": true
},
"id": "ev-1700000900",
"trigger": "load",
"entity": "order",
"action": "complete",
"timestamp": 1700000900000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "express",
"platform": "server"
}
}{
"name": "Purchase",
"data": {
"map": {
"event_metadata": {
"map": {
"value_decimal": "data.value",
"currency": {
"key": "data.currency",
"value": "EUR"
},
"item_count": {
"fn": {
"$code": "e=>e.nested.filter(e=>\"product\"===e.entity).length"
}
},
"products": {
"loop": [
"nested",
{
"condition": {
"$code": "e=>\"object\"==typeof e&&null!==e&&\"entity\"in e&&\"product\"===e.entity"
},
"map": {
"id": "data.id",
"name": "data.name",
"category": {
"key": "data.category",
"value": "uncategorized"
}
}
}
]
}
}
}
}
}
}sendServer("https://ads-api.reddit.com/api/v2.0/conversions/events/a2_abcdef123456", "{\"data\":{\"events\":[{\"event_at\":\"2023-11-14T22:28:20.000Z\",\"event_at_ms\":1700000900000,\"event_type\":{\"tracking_type\":\"Purchase\"},\"user\":{},\"event_metadata\":{\"conversion_id\":\"ev-1700000900\",\"value_decimal\":249.99,\"currency\":\"EUR\",\"item_count\":1,\"products\":[{\"id\":\"SKU-A1\",\"name\":\"Everyday Ruck Snack\",\"category\":\"bags\"}]}}]}}", {
"headers": {
"Authorization": "Bearer s3cr3t"
}
})Search
A search submit is sent to Reddit as a Search conversion with an item count in event_metadata.
{
"name": "search submit",
"data": {
"term": "walkerOS destinations"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"lang": "elb"
},
"custom": {
"completely": "random"
},
"user": {
"id": "user-101"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev-1700000905",
"trigger": "test",
"entity": "search",
"action": "submit",
"timestamp": 1700000905000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "express",
"platform": "server"
}
}{
"name": "Search",
"data": {
"map": {
"event_metadata": {
"map": {
"item_count": {
"value": 1
}
}
}
}
}
}sendServer("https://ads-api.reddit.com/api/v2.0/conversions/events/a2_abcdef123456", "{\"data\":{\"events\":[{\"event_at\":\"2023-11-14T22:28:25.000Z\",\"event_at_ms\":1700000905000,\"event_type\":{\"tracking_type\":\"Search\"},\"user\":{},\"event_metadata\":{\"conversion_id\":\"ev-1700000905\",\"item_count\":1}}]}}", {
"headers": {
"Authorization": "Bearer s3cr3t"
}
})Sign up
A user signup is sent to Reddit as a SignUp conversion with hashed user identifiers.
{
"name": "user signup",
"data": {
"method": "email"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"lang": "elb"
},
"custom": {
"completely": "random"
},
"user": {
"id": "new-user-1",
"email": "new@example.com"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev-1700000904",
"trigger": "test",
"entity": "user",
"action": "signup",
"timestamp": 1700000904000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "express",
"platform": "server"
}
}{
"name": "SignUp",
"data": {
"map": {
"user": {
"map": {
"email": "user.email",
"external_id": "user.id"
}
}
}
}
}sendServer("https://ads-api.reddit.com/api/v2.0/conversions/events/a2_abcdef123456", "{\"data\":{\"events\":[{\"event_at\":\"2023-11-14T22:28:24.000Z\",\"event_at_ms\":1700000904000,\"event_type\":{\"tracking_type\":\"SignUp\"},\"user\":{\"email\":\"f0030501023327437b06e5c6f87df7871b8e704ae608d1d0b7b24fdd2a06c716\",\"external_id\":\"b45cf5f6ebc2c6974ea3bd9fab19f8cc3a7cf63054727a9fcd22f1fda97d6dde\"},\"event_metadata\":{\"conversion_id\":\"ev-1700000904\"}}]}}", {
"headers": {
"Authorization": "Bearer s3cr3t"
}
})Failures
A response outside the 2xx range, a network error, or no answer within 5 seconds fails the event: the push answers failed with the code transport (with the HTTP status) or timeout, the event goes to the dead-letter queue, and the collector logs one ERROR line. Any 2xx answer counts as delivered: the destination does not read the response body. Without accessToken or pixelId the destination does not start: every push answers failed with the code config, and the collector logs destination init failed. A rule with silent: true sends nothing.
Client IP and user agent
The destination sends the client IP as user.ip_address and the user agent as user.user_agent by default. The ip and userAgent settings resolve against { ingest, event } and default to ["ingest.ip", "event.user.ip"] and ["ingest.userAgent", "event.user.userAgent"], so they fill in whenever the source provides them (see the config.ingest recipe on the Express source). Both are SHA-256 hashed like the other identity fields. A value your mapping sets for user.ip_address or user.user_agent wins. A value that resolves to nothing is not sent. Set either setting to false to turn it off, or to another mapping value to read it elsewhere.
Consent
The quickstart sets no config.consent, so Reddit receives every event, whatever consent the event carries. To send only events with consent, add consent: { marketing: true } to config, next to settings (with several keys listed, one granted key is enough). An event without that consent is skipped or queued, depending on the collector's consentDenied. Server flows built by the CLI skip it and count it in skipped. With startFlow it waits in the destination's queue by default: a later event that carries consent does not release it, and only a walker consent command does, which then sends the waiting events of every user at once. Pass consentDenied: 'skip' to startFlow to skip such events instead (see Gate a destination with consent and consent-denied events on a server).
Event mapping
Reddit uses a rigid taxonomy. Map walkerOS events to a standard tracking_type via each rule's name field:
| walkerOS Event | Reddit tracking_type |
|---|---|
page view | PageVisit |
product view | ViewContent |
search submit | Search |
product add | AddToCart |
product wishlist | AddToWishlist |
order complete | Purchase |
form submit | Lead |
user signup | SignUp |
Any non-standard name becomes { tracking_type: 'Custom', custom_event_name: '<name>' } automatically. Prefer a standard type where one fits.
"mapping": {
"order": {
"complete": {
"name": "Purchase",
"data": {
"map": {
"event_metadata": {
"map": {
"value_decimal": "data.value",
"currency": "data.currency",
"item_count": { "value": 1 }
}
}
}
}
}
}
}event_metadata structure
Reddit takes conversion details under event_metadata: map them into event_metadata.map. A key mapped at the top level of the data is sent at the top level of the event. Products belong in event_metadata.products[] with { id, name?, category }.
Hashing
The destination SHA-256 hashes these keys of the user object before sending: email, external_id, ip_address, user_agent, idfa, aaid. In a rule's data or the destination's config.data, map them under user; the setting that applies to every event is settings.user_data. Map personal data only to these keys.
- Every other key is sent in clear text.
uuid,opt_out,screen_dimensionsanddata_processing_optionsare sent as mapped, and so is any other key underuser: nothing checks the names, sophone_numberoremreaches Reddit unhashed. user_dataindata(a rule's orconfig.data) is not the user object. Other conversion API destinations use that name; this one sends it unhashed at the top level of the event, like any other key mapped outsideuser.- Values are hashed exactly as mapped, without normalization. Normalize them upstream in the format Reddit expects, for example the email trimmed and lowercased.
Reddit hashes ip_address and user_agent, which Meta CAPI and Pinterest CAPI pass through as plaintext. Be sure to pass the raw values, not pre-hashed ones, unless you use doNotHash.
If a value is already hashed or you want to skip hashing for a specific field, use doNotHash:
"settings": {
"accessToken": "$secret.REDDIT_ACCESS_TOKEN",
"pixelId": "YOUR_PIXEL_ID",
"doNotHash": ["email"]
}Deduplication
Each event is sent with event_metadata.conversion_id set to the walkerOS event id. A conversion_id that your mapping sets under event_metadata replaces it.
Test mode
Set test_mode: true in settings to send "test_mode": true as a top-level boolean in the request body. Useful during development.
"settings": {
"accessToken": "$secret.REDDIT_ACCESS_TOKEN",
"pixelId": "YOUR_PIXEL_ID",
"test_mode": true
}