Snapchat Conversions API

Server Source code Package 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

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 | CLI reference

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
`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`		Event action source (default WEB)
`doNotHash`	`Array<string>`	User data fields to skip hashing
`user_data`	`Record<string, string>`	Mapping for user data fields
`testMode`	`boolean`	When true, sends events to /events/validate instead of /events for testing

* Required fields

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 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

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

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

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

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

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

💡 Need implementation support?

elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)

Installation​

Configuration​

Settings​

Mapping​

Examples

Add to cart

Sign up

Page view

Purchase

Event mapping​

custom_data structure​

Hashing​

Deduplication​

Test mode​

Links​

Installation

Configuration

Settings

Mapping

Event mapping

custom_data structure

Hashing

Deduplication

Test mode

Links