> Part of the walkerOS documentation. Project overview and full index: # Snapchat Conversions API [Server](#)[ ](https://github.com/elbwalker/walkerOS/tree/main/packages/server/destinations/snapchat) [Source code](https://github.com/elbwalker/walkerOS/tree/main/packages/server/destinations/snapchat)[ ](https://www.npmjs.com/package/@walkeros/server-destination-snapchat) [Package](https://www.npmjs.com/package/@walkeros/server-destination-snapchat) Beta Server-side event delivery to Snapchat's Conversions API v3 for enhanced conversion tracking, bypassing browser limitations and improving match quality for ad optimization. Where this fits Snapchat Conversions API is a **server destination** in the walkerOS flow: Sends events server-side to Snapchat's Conversions API using raw HTTP (no SDK). Identity fields (\`em\`, \`ph\`, \`fn\`, \`ln\`, \`db\`, \`ge\`, \`ct\`, \`st\`, \`zp\`, \`country\`, \`external\_id\`) are SHA-256 hashed before sending. Events include a stable \`event\_id\` for deduplication with the Snap Pixel. ## Installation[​](#installation "Direct link to Installation") ``` npm install @walkeros/server-destination-snapchat ``` * Integrated * Bundled ``` import { startFlow } from '@walkeros/collector'; import { destinationSnapchat } from '@walkeros/server-destination-snapchat'; await startFlow({ destinations: { snapchat: { code: destinationSnapchat, config: { settings: { accessToken: 'YOUR_ACCESS_TOKEN', pixelId: 'YOUR_PIXEL_ID', }, }, }, }, }); ``` Add to your `flow.json` destinations: ``` "destinations": { "snapchat": { "package": "@walkeros/server-destination-snapchat", "import": "destinationSnapchat", "config": { "settings": { "accessToken": "YOUR_ACCESS_TOKEN", "pixelId": "YOUR_PIXEL_ID" } } } } ``` [See bundled mode setup](https://www.walkeros.io/docs/getting-started/modes/bundled.md) | [CLI reference](https://www.walkeros.io/docs/apps/cli.md) ## Configuration[​](#configuration "Direct link to Configuration") This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see [destination configuration](https://www.walkeros.io/docs/destinations.md#configuration). Package-specific fields live under `config.settings` and are listed below. ## Settings[​](#settings "Direct link to Settings") | Property | Type | Description | More | | --------------- | ---------------------------------- | -------------------------------------------------------------------------- | ---- | | `accessToken*` | `string` | Long-lived Conversions API access token from Snapchat Ads Manager | | | `pixelId*` | `string` | Snap Pixel ID | | | `url` | `string` | Custom Conversions API base URL (default https\://tr.snapchat.com/v3/) | | | `action_source` | `'WEB' \| 'MOBILE_APP' \| 'OFFLIN` | Event action source (default WEB) | | | `doNotHash` | `Array` | User data fields to skip hashing | | | `user_data` | `Record` | Mapping for user data fields | | | `testMode` | `boolean` | When true, sends events to /events/validate instead of /events for testing | | \* Required fields ## Mapping[​](#mapping "Direct link to Mapping") This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see [mapping](https://www.walkeros.io/docs/mapping.md). ## Examples ### Add to cart A product add is sent to Snapchat as an ADD\_CART conversion with value and product details. Event ``` { "name": "product add", "data": { "id": "SKU-B2", "name": "Running Shoes", "price": 89.99, "color": "blue" }, "context": { "shopping": [ "intent", 0 ] }, "globals": { "pagegroup": "shop" }, "custom": { "completely": "random" }, "user": { "id": "us3r", "device": "c00k13", "session": "s3ss10n" }, "nested": [ { "entity": "product", "data": { "id": "SKU-B2", "name": "Running Shoes", "price": 89.99, "quantity": 1 } } ], "consent": { "functional": true }, "id": "e1f2a3b4c5d60002", "trigger": "click", "entity": "product", "action": "add", "timestamp": 1700000901000, "timing": 3.14, "source": { "count": 1, "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9", "type": "browser", "platform": "web", "url": "https://shop.example.com/products/running-shoes" } } ``` Mapping ``` { "name": "ADD_CART", "data": { "map": { "custom_data": { "map": { "value": "data.price", "currency": { "value": "EUR" }, "contents": { "loop": [ "nested", { "condition": { "$code": "e=>h(e)&&\"product\"===e.entity" }, "map": { "id": "data.id", "item_price": "data.price", "quantity": { "key": "data.quantity", "value": 1 } } } ] } } } } } } ``` Out ``` sendServer("https://tr.snapchat.com/v3/p1x3l1d/events?access_token=s3cr3t", "{\"data\":[{\"event_name\":\"ADD_CART\",\"event_time\":1700000901,\"action_source\":\"WEB\",\"event_id\":\"e1f2a3b4c5d60002\",\"user_data\":{},\"custom_data\":{\"value\":89.99,\"currency\":\"EUR\",\"contents\":[{\"id\":\"SKU-B2\",\"item_price\":89.99,\"quantity\":1}]},\"event_source_url\":\"https://shop.example.com/products/running-shoes\"}]}") ``` ### Sign up A newsletter form submission is sent to Snapchat as a SIGN\_UP conversion with a hashed email. Event ``` { "name": "form submit", "data": { "type": "newsletter" }, "context": { "dev": [ "test", 1 ] }, "globals": { "lang": "elb" }, "custom": { "completely": "random" }, "user": { "email": "user@example.com" }, "nested": [ { "entity": "child", "data": { "is": "subordinated" } } ], "consent": { "functional": true }, "id": "e1f2a3b4c5d60004", "trigger": "test", "entity": "form", "action": "submit", "timestamp": 1700000903000, "timing": 3.14, "source": { "count": 1, "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9", "type": "browser", "platform": "web", "url": "https://example.com/contact" } } ``` Mapping ``` { "name": "SIGN_UP", "data": { "map": { "user_data": { "map": { "em": "user.email" } }, "custom_data": { "map": { "sign_up_method": { "value": "newsletter" } } } } } } ``` Out ``` sendServer("https://tr.snapchat.com/v3/p1x3l1d/events?access_token=s3cr3t", "{\"data\":[{\"event_name\":\"SIGN_UP\",\"event_time\":1700000903,\"action_source\":\"WEB\",\"event_id\":\"e1f2a3b4c5d60004\",\"user_data\":{\"em\":\"b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514\"},\"custom_data\":{\"sign_up_method\":\"newsletter\"},\"event_source_url\":\"https://example.com/contact\"}]}") ``` ### Page view A page view is forwarded to Snapchat with the event source URL and no extra custom data. Event ``` { "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": "us3r", "device": "c00k13", "session": "s3ss10n" }, "nested": [ { "entity": "child", "data": { "is": "subordinated" } } ], "consent": { "functional": true }, "id": "e1f2a3b4c5d60003", "trigger": "load", "entity": "page", "action": "view", "timestamp": 1700000902000, "timing": 3.14, "source": { "count": 1, "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9", "type": "browser", "platform": "web", "url": "https://example.com/docs/" } } ``` Out ``` sendServer("https://tr.snapchat.com/v3/p1x3l1d/events?access_token=s3cr3t", "{\"data\":[{\"event_name\":\"page view\",\"event_time\":1700000902,\"action_source\":\"WEB\",\"event_id\":\"e1f2a3b4c5d60003\",\"user_data\":{},\"custom_data\":{},\"event_source_url\":\"https://example.com/docs/\"}]}") ``` ### Purchase A completed order is sent to the Snapchat Conversions API as a PURCHASE with value, currency, and contents. Event ``` { "name": "order complete", "data": { "id": "ORD-300", "total": 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": "Widget Pro", "price": 124.99, "quantity": 2 } } ], "consent": { "functional": true }, "id": "e1f2a3b4c5d60001", "trigger": "load", "entity": "order", "action": "complete", "timestamp": 1700000900000, "timing": 3.14, "source": { "count": 1, "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9", "type": "browser", "platform": "web", "url": "https://shop.example.com/checkout/complete" } } ``` Mapping ``` { "name": "PURCHASE", "data": { "map": { "custom_data": { "map": { "value": "data.total", "currency": { "key": "data.currency", "value": "EUR" }, "transaction_id": "data.id", "contents": { "loop": [ "nested", { "condition": { "$code": "e=>h(e)&&\"product\"===e.entity" }, "map": { "id": "data.id", "item_price": "data.price", "quantity": { "key": "data.quantity", "value": 1 } } } ] } } }, "user_data": { "map": { "external_id": "user.id" } } } } } ``` Out ``` sendServer("https://tr.snapchat.com/v3/p1x3l1d/events?access_token=s3cr3t", "{\"data\":[{\"event_name\":\"PURCHASE\",\"event_time\":1700000900,\"action_source\":\"WEB\",\"event_id\":\"e1f2a3b4c5d60001\",\"user_data\":{\"external_id\":\"fcdec6df4d44dbc637c7c5b58efface52a7f8a88535423430255be0bb89bedd8\"},\"custom_data\":{\"value\":249.99,\"currency\":\"EUR\",\"transaction_id\":\"ORD-300\",\"contents\":[{\"id\":\"SKU-A1\",\"item_price\":124.99,\"quantity\":2}]},\"event_source_url\":\"https://shop.example.com/checkout/complete\"}]}") ``` ## Event mapping[​](#event-mapping "Direct link to Event mapping") Map walkerOS events to Snapchat standard event names via each rule's `name` field. Snapchat uses **UPPERCASE** standard event names (e.g. `PURCHASE`, not `Purchase`). ``` "mapping": { "order": { "complete": { "name": "PURCHASE", "data": { "map": { "custom_data": { "map": { "value": "data.total", "currency": "data.currency", "transaction_id": "data.id" } } } } } } } ``` ### custom\_data structure[​](#custom_data-structure "Direct link to custom_data structure") Unlike Meta's CAPI (which places properties flat on the event root), Snapchat requires event properties to be nested under `custom_data`. Always map into `custom_data.map`. ## Hashing[​](#hashing "Direct link to Hashing") The destination automatically SHA-256 hashes the 11 standard identity fields before sending: `em`, `ph`, `fn`, `ln`, `db`, `ge`, `ct`, `st`, `zp`, `country`, `external_id`. Pass raw values and hashing is handled for you. Non-hashable fields pass through as-is: `sc_cookie1`, `client_ip_address`, `client_user_agent`, `sc_click_id`, `idfv`, `madid`. If a value is already hashed or you want to skip hashing for a specific field, use `doNotHash`: ``` "settings": { "accessToken": "YOUR_ACCESS_TOKEN", "pixelId": "YOUR_PIXEL_ID", "doNotHash": ["em"] } ``` ## Deduplication[​](#deduplication "Direct link to Deduplication") Each event is sent with `event_id` set to the walkerOS event `id`. If you also run the Snap Pixel in the browser, Snapchat deduplicates server and browser events that share the same `event_id` and `event_name` within a 48h window, so conversions are not double-counted. ## Test mode[​](#test-mode "Direct link to Test mode") Set `testMode: true` to send events to Snapchat's `/events/validate` endpoint for validation instead of the live `/events` endpoint. Useful during development. Events validated via this endpoint do **not** count toward ads delivery or optimization. ``` "settings": { "accessToken": "YOUR_ACCESS_TOKEN", "pixelId": "YOUR_PIXEL_ID", "testMode": true } ``` ## Links[​](#links "Direct link to Links") * [Snapchat Conversions API documentation](https://businesshelp.snapchat.com/s/article/conversions-api) * [CAPI parameters reference](https://businesshelp.snapchat.com/s/article/capi-parameters)