> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datalyr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapchat Ads

> Authorize Snapchat and deliver conversions to a Snap Pixel.

When you finish, one Datalyr event reaches the Snapchat Conversions API and returns `VALID`.

## Before you start

| Requirement    | Detail                                                                       |
| -------------- | ---------------------------------------------------------------------------- |
| Snapchat login | Has access to the organization that owns the pixel                           |
| Snap Pixel ID  | **Snapchat Ads Manager → Events Manager**, the pixel ID under the pixel name |
| Snap App ID    | Only for app-install conversions. **Ads Manager → Apps**                     |
| A live event   | The trigger event exists in **Events**                                       |

Snapchat has no primary-account step. The destination asset lives on each rule, not on the connection.

## Connect Snapchat

<Steps>
  <Step title="Open Sources">
    Open **Sources**. Find the **Snapchat Ads** card.
  </Step>

  <Step title="Authorize">
    Select **connect**. Complete Snapchat authorization. Approve the conversions access.
  </Step>

  <Step title="Confirm the state">
    Confirm the card no longer reads `not connected`.
  </Step>
</Steps>

## Create the rule

<Steps>
  <Step title="Open the editor">
    Open **Conversions**. Select **manage rules**. Select **new rule**.
  </Step>

  <Step title="Set the trigger">
    Fill **rule name**. Pick the **trigger event**. Pick **Snapchat** as **target platform**.
  </Step>

  <Step title="Pick the pixel">
    Pick the pixel under **Snapchat Pixel ID**. Paste the ID if the list is empty.
  </Step>

  <Step title="Add an app asset">
    For app-install conversions, pick a **Snap App ID**. Leave it blank for web and server events.
  </Step>

  <Step title="Map the event">
    Select **next**. Pick the **platform standard event**. Set **value** and **currency**. Select **save**.
  </Step>
</Steps>

## Reference

| Mode | Endpoint                                                                    |
| ---- | --------------------------------------------------------------------------- |
| Live | `POST https://tr.snapchat.com/v3/{asset_id}/events?access_token=…`          |
| Test | `POST https://tr.snapchat.com/v3/{asset_id}/events/validate?access_token=…` |

Snapchat takes the access token as a query parameter, not as an `Authorization` header. `{asset_id}` is the Snap Pixel ID, or the Snap App ID for a `MOBILE_APP` event.

### Standard events

We send these `event_name` values: `PURCHASE`, `ADD_CART`, `START_CHECKOUT`, `ADD_BILLING`, `VIEW_CONTENT`, `SIGN_UP`, `PAGE_VIEW`, `SUBSCRIBE`, `START_TRIAL`, `SEARCH`, `ADD_TO_WISHLIST`, `SAVE`, `LIST_VIEW`, `CUSTOM_EVENT_1`.

### `action_source`

| Condition                                | `action_source` | Extra payload                                                                             |
| ---------------------------------------- | --------------- | ----------------------------------------------------------------------------------------- |
| App event and the rule has a Snap App ID | `MOBILE_APP`    | `app_data` with `app_id`, `advertiser_tracking_enabled`, and a 16-element `extinfo` array |
| The event has a page URL                 | `WEB`           | `event_source_url`                                                                        |
| Everything else, including webhooks      | `OFFLINE`       | none                                                                                      |

An app event without a Snap App ID falls back to `WEB` or `OFFLINE` on the pixel. Snapchat drops an app conversion sent as `MOBILE_APP` under a Pixel ID, so we never do that.

### Matching fields in `user_data`

| Field               | Source                                                             | Normalization before SHA-256                                                                                                    |
| ------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `em`                | email in the event, the user profile, or an email-shaped `user_id` | lowercase, trim; rejected unless it matches `x@y.z`                                                                             |
| `ph`                | phone                                                              | digits only, country code kept, leading `+` removed                                                                             |
| `fn`, `ln`          | first and last name                                                | lowercase, trim                                                                                                                 |
| `ct`                | city, or `geo_city`                                                | lowercase, every character outside `a-z` removed                                                                                |
| `st`                | state, or `geo_region`                                             | 2-letter lowercase code                                                                                                         |
| `zp`                | postal code                                                        | lowercase, spaces and dashes removed, first 5 characters for `us`                                                               |
| `country`           | country, or `geo_country_code`                                     | lowercase ISO alpha-2; falls back to the raw lowercase value                                                                    |
| `external_id`       | mapped ID, else the `distinct id`                                  | hashed verbatim, with no lowercase and no trim                                                                                  |
| `sc_click_id`       | the `ScCid` URL parameter                                          | not hashed                                                                                                                      |
| `sc_cookie1`        | the `_scid` first-party cookie                                     | not hashed                                                                                                                      |
| `client_ip_address` | event IP                                                           | not hashed                                                                                                                      |
| `client_user_agent` | browser user agent                                                 | not hashed; dropped when it starts with `node`, `undici`, `axios`, `got`, `curl`, `python`, `java`, `go-http-client`, or `wget` |
| `madid`, `idfv`     | advertising and vendor IDs, `MOBILE_APP` only                      | not hashed                                                                                                                      |

Snapchat appends `ScCid` to the landing URL, never `sclid`. We store the value as `sclid`, so that name appears in event payloads.

We drop an `external_id` that starts with `stripe_`, because Snapchat can never match it.

### Value and `custom_data`

| Field        | Rule                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------- |
| `value`      | The rule's `value_path`, else `value_static`, else `value` / `revenue` / `total` / `amount` |
| `currency`   | The rule's currency, else the event's currency, else `USD`                                  |
| `num_items`  | Sent as a string. Snapchat rejects a number here                                            |
| Other fields | `content_ids`, `order_id`, `search_string`                                                  |

### Deduplication

We send `event_id`, the same UUID the browser Snap Pixel fires with, and Snapchat collapses the pair into one conversion.

The attribution lookup window is 28 days from the click.

## Verify

1. Open **Conversions**. Select **manage rules**. Open your rule.
2. Select **send test event**. We post to the `/validate` endpoint.
3. Confirm the delivery row's response body reads `"status": "VALID"`.
4. Trigger one real event.
5. Open **Snapchat Ads Manager → Events Manager**. Confirm the event appears.

## When it does not work

| Symptom                                                 | Cause                                                   | Check                                         | Fix                                               |
| ------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------- |
| Delivery `skipped`, reason `pixel_id_not_configured`    | The rule has no Snap Pixel ID                           | The **Snapchat Pixel ID** field on the rule   | Paste the pixel ID. Save the rule                 |
| Delivery `skipped`, reason `snap_app_id_not_configured` | An app event resolved to `MOBILE_APP` with no app asset | The **Snap App ID** field on the rule         | Add the Snap App ID, or accept `OFFLINE` delivery |
| Delivery `skipped`, reason `zero_value_purchase`        | A `PURCHASE` resolved to a value of 0                   | The `value_path` against a real event payload | Point `value_path` at the amount field            |
| Response body `"status": "INVALID"`                     | Snapchat rejected a field                               | The `reason` in the same response body        | Fix the named field in the rule                   |
| HTTP 401 or 403                                         | The Snapchat token expired or lost access               | The card state in **Sources**                 | Select **disconnect**, then reconnect             |
| HTTP 429 or 5xx                                         | Snapchat throttled or faulted                           | The delivery row's response body              | Nothing. We retry through the dead-letter queue   |
| `VALID`, nothing in Events Manager                      | The event landed under a different pixel                | The asset ID in the request payload           | Repick the pixel in the rule                      |
| No delivery row at all                                  | No rule matched the event                               | The rule's trigger event name in **Events**   | Correct the trigger event name. Enable the rule   |

## Next

* [Conversion delivery](/advanced/conversion-delivery): retry, dedup, and status rules for every platform.
* [Conversions](/product/conversions): read one delivery row and its response body.
* [Attribution](/attribution/index): how `ScCid` reaches a server-side purchase.