Supported Keys for Snapchat Conversions API
See list of events and the parameters you can send to Snapchat
This article lists all the event types and their parameters that you can send to Snapchat CAPI. There may be some parameters you are required to send depending on the event type. For the best performance, you should always send additional parameters if they are available on your domain(s).
Required Parameters
You are required to provide the following parameters when creating the request to send a conversion event.
| Attribute | Description | Possible Value |
|---|---|---|
event_type | Event type required for all web, app, and offline events. | PURCHASE, SAVE, START_CHECKOUT, ADD_CART, VIEW_CONTENT, ADD_BILLING, SIGN_UP, SEARCH, PAGE_VIEW, SUBSCRIBE, AD_CLICK, AD_VIEW, COMPLETE_TUTORIAL, LEVEL_COMPLETE, INVITE, LOGIN, SHARE, RESERVE, ACHIEVEMENT_UNLOCKED, ADD_TO_WISHLIST, SPENT_CREDITS, RATE, START_TRIAL, LIST_VIEW, APP_INSTALL, APP_OPEN, CUSTOM_EVENT_1, CUSTOM_EVENT_2, CUSTOM_EVENT_3, CUSTOM_EVENT_4, CUSTOM_EVENT_5 |
event_time | The Epoch timestamp for the conversion happening. We can handle second level or millisecond level granularity. However, we do encourage requests to provide millisecond level granularity. Required for all web, app, and offline events. Please note: Please note that the timestamp cannot be more than 37 days in the past. | 1633684680 |
event_id | Event ID (or Transaction ID on Snap side) tied to the conversion event. This is an important field to include for deduplication | 1234 |
event_source_url | The URL of the web page where the event took place. Must include protocol (eg http, https) | https://www.example.com/purchase |
user_data | Use this property to pass the partner_id field containing ATS Envelope. | partner_id |
Required Parameters Per Event Type
In addition to the required parameters above, you are sometimes required to pass additional parameters which differ based on your event_type.
| Event type | Required Parameters | Recommended Parameters |
|---|---|---|
PURCHASE | price, currency | item_ids,number_items |
ADD_CART | item_category, item_ids, number_items |
Other Supported Parameters
You can send additional data by passing the parameters below under custom_data. Check out the request example to see what it looks like.
| Attribute | Description | Examples |
|---|---|---|
app_id | The unique ID (app_id) assigned for a given application. It should be numeric for iOS, and the human interpretable string (example: com.snapchat.android) for Android. Only required for app events. See Snapchat's article "Set Up and Manage Your Snap App ID" to learn more. | The app_id for Snapchat is 447188370 (iOS) and com.snapchat.android (Android) |
snap_app_id | The Snap App ID associated with your app (a unique code generated in Ads Manager and included in your MMP dashboard). Only required for app events. | 07b517bb-9cdb-42ef-ba77-9dd9a9eb2dc1 |
event_tag | Custom event set label. Not currently surfaced in measurement or audience generation, but may become usable in the future. | in-store, weekend sales, back-to-school campaign |
item_category | Item or Category. Can be single category or an array. | "shoes"or ["coats, Shoes, umbrellas"] |
item_ids | International Article Number (EAN) when applicable, or other product or category identifier. This can be a single item ID, an array, or a list of item IDs to be separated by “,” or “;” | "sku001"or "sku001,sku002,sku003"or "sku001;sku002;sku003"or ["sku001;sku002;sku003"] |
description | A string description for additional info | This is a free form text description with no specific format. Note: max 1024 characters |
number_items | Number of items | "1", "1,2,3", "1;2;3" |
price | Value of the purchase. Snapchat allows a list of prices to be separated with “,” or “;” Required for PURCHASE event. | 123,145,500 etc. Note: If a list is provided Snapchat will total up the prices server-side. |
currency | Standard ISO 4217 code Required for PURCHASE event. | Supported currencies: USD, AED, AUD, BGN, BRL, CAD, CHF, CLP, CNY, COP,CZK, DKK, EGP, EUR, GBP, GIP, HKD, HRK, HUF, IDR, ILS, INR, JPY, KRW, KWD, KZT, LBP, MXN, MYR, NGN, NOK, NZD, PEN, PHP, PKR, PLN, QAR,RON, RUB, SAR, SEK, SGD, THB, TRY, TWD, TZS, UAH, VND, ZAR, ALL, BHD, DZD, GHS, IQD, ISK, JOD, KES, MAD, OMR, XOF |
level | Represents a level in the context of a game | |
search_string | The text that was searched for. | shoes umbrellas coats |
sign_up_method | A string indicating the sign up method. | Email Twitter etc |
att_status | Used to indicate an OPT_IN or OPT_OUT for MOBILE_APP events. For users of iOS 14.5 and above, please set this parameter to the user’s ATT Authorization Status. For all other iOS users, please set this to AUTHORIZED. | AUTHORIZED, DENIED, RESTRICTED, NOT_DETERMINED |
data_use | Used to indicate an OPT_IN or OPT_OUT for WEB events. For users of iOS 14.5 and above that are OPT_OUT, set this parameter’s value to a list that has a single element of the value lmu. Otherwise, do not set this parameter. | ['lmu'] |
device_model | The user’s device model. | iPhone12Pro, iPhone11ProMax, GalaxyS20Ultra5G |
os_version | The user’s OS version. | 14.4.1, 15.6, 12 |
click_id | The ID value stored in the landing page URL’s &ScCid= query parameter. Using this ID improves ad measurement performance. We also encourage advertisers who are using click_id to pass the full URL in the event_source_url field. For more details, refer to Snapchat's article "Sending a Click ID". | 7b3a7917-a82a-47e8-9728-e1b3b045abb2 |
uuid_c1 | If you are using the Pixel SDK, you can access a 1st party cookie by looking at the _scid value under your domain. We highly recommend you pass this, as doing so will increase your user match rate. | 57cf8a96-99ff-4260-a6b0-219820d2860e |
brands | Brands associated with the item_ids in the conversion event. This parameter’s value should be formatted as a list of strings. | ["brand1", "brand2"] |
delivery_method | Indicates the delivery method of the order. Please set to either in_store, curbside, or delivery. | in_store, curbside, or delivery |
customer_status | Indicates the registration status of the customer. Please set to either new, returning, or reactivated. | new, returning, activated |
country | Country associated with the conversion. Must be provided as a two letter ISO 3166 alpha-2 country code. | US, GB, JP |
region | State or region associated with the conversion. If the country is US, provide a two letter State code (CA, WA), otherwise provide the full region name. | CA,WA |
contents | A list of JSON objects that contain the product IDs associated with the event plus information about the products. Available fields: id, quantity, item_price, delivery_category. | ["id": "sku_123", "quantity": 1, "item_price": 89.99, "delivery_category": "standard"] |
content_type | Should be set to product or product_group: Use product if the keys you send represent products. Sent keys could be content_ids or contents. Use product_group if the keys you send in content_ids represent product groups. Product groups are used to distinguish products that are identical but have variations such as color, material, size or pattern. | 'product' |
brands | Brand associated with the conversion. | ["Nike", "Adidas"] |
Updated 8 months ago