Skip to main content

Custom Conversions

Custom Conversions enable granular measurement and optimization by filtering standard Pixel or App events based on specific parameter values—without requiring additional client-side code changes.

Intro​

Custom Conversions enable granular measurement, reporting, and now optimization (open beta) by filtering standard events based on specific parameter values. By defining rules (for example, Price > 50 or Item Category = 'Premium'), developers can segment standard Pixel or App events into distinct conversion actions without requiring additional code changes on the client side. Custom Conversion Rules should be created within Ads Manager first before sending events.

The parameters you match on come from the event you send via the Snap Pixel or the Conversions API. Rule keys use the Snap Pixel parameter names; if you send events via CAPI v3, some custom_data field names differ from the rule key — see the CAPI Parameter to Rule Key Mapping below.

Base URL: https://adsapi.snapchat.com/v1

Endpoints​

Pixel CC Endpoint​

Using a Pixel ID

{base_url}/pixels/{pixel_id}/custom_conversions

App CC Endpoint​

Using a Snap App ID

{base_url}/mobile_apps/{app_id}/custom_conversions

Custom Conversion Endpoint​

{base_url}/custom_conversions/{custom_conversion_id}

Custom Conversion Object​

Each Custom Conversion object contains a name, description, event type, and the rules that need to be met.

{
  "name": "Some Conversion Name",
  "description": "Conversion from Landing Page A",
  "event_type": "PURCHASE",
  "rules": [
    {...},
    {...}
  ]
}

Rule Object​

Each rule object contains a key, the values, and the operator.

{
  "key": "EVENT_TAG",
  "values": ["tag-1", "tag-7"],
  "operator": "I_CONTAINS"
}

Custom Conversion Rule Keys​

KeyTypeKeyType
event_tagstringitem_idstring
item_categorystringcurrencystring
search_stringstringsign_up_methodstring
page_urlstringcategorystring
category_idstringbrandstring
delivery_methodstringcustomer_statusstring
pricenumbernumber_itemsnumber

CAPI Parameter to Rule Key Mapping​

Custom Conversion rule keys match the Snap Pixel (SDK) parameter names. When you send events through the Conversions API (CAPI v3), several custom_data fields use different names than the rule key you match on. Map the field you send to the rule key you build the rule with:

Custom Conversion rule keyCAPI v3 custom_data fieldSnap Pixel (SDK) field
customer_statusstatuscustomer_status
item_categorycontent_categoryitem_category
item_idcontent_idsitem_ids
number_itemsnum_itemsnumber_items
pricevalue (or contents[].item_price)price
currencycurrencycurrency
search_stringsearch_stringsearch_string
sign_up_methodsign_up_methodsign_up_method
brandbrandsbrands
delivery_methodcontents[].delivery_categorydelivery_method
event_tagevent_tagevent_tag
page_urlevent_source_urlpage_url

You send custom_data.status in your CAPI payload, but you build the rule on customer_status. They refer to the same value — the API just uses a different field name than the rule key. The same pattern applies to content_category → item_category, content_ids → item_id, and num_items → number_items.

Custom Conversion Rule Operators​

I_* indicates case insensitivity

RuleTypeRuleType
EQUAL_TOstring or numberNOT_EQUAL_TOstring or number
I_CONTAINSstringI_NOT_CONTAINSstring
CONTAINSstringNOT_CONTAINSstring
STARTS_WITHstringI_STARTS_WITHstring
I_EQUAL_TOstringI_NOT_EQUAL_TOstring
LESS_THANnumberLESS_THAN_OR_EQUALSnumber
GREATER_THANnumberGREATER_THAN_OR_EQUALSnumber

End-to-End Example: Segment by Customer Status​

This example creates a "New Customer Purchases" conversion by combining a CAPI event with a Custom Conversion rule.

Step 1 — Send the event with status in custom_data (CAPI v3):

{
  "event_name": "PURCHASE",
  "event_time": 1705423250,
  "action_source": "WEB",
  "event_source_url": "https://shop.example.com/checkout/success",
  "event_id": "order-98765",
  "user_data": {
    "em": ["<sha256_lowercased_email>"],
    "client_ip_address": "199.29.1.2",
    "client_user_agent": "Mozilla/5.0 ...",
    "sc_cookie1": "F340A595-07F1-4441-8BAA-85459CC674A2"
  },
  "custom_data": {
    "currency": "USD",
    "value": "142.52",
    "order_id": "order-98765",
    "content_ids": ["SKU1234"],
    "content_category": "shoes",
    "num_items": "1",
    "status": "new"
  }
}

Step 2 — Create the Custom Conversion, matching on the customer_status rule key:

Method: POST
Endpoint: {base_url}/pixels/{pixel_id}/custom_conversions
{
  "custom_conversions": [
    {
      "name": "New Customer Purchases",
      "description": "PURCHASE events where the customer is new",
      "event_type": "PURCHASE",
      "rules": [
        {
          "key": "customer_status",
          "values": ["new"],
          "operator": "I_EQUAL_TO"
        }
      ]
    }
  ]
}

Every PURCHASE event on this pixel whose custom_data.status equals new now counts toward this Custom Conversion, which can then be used for reporting and optimization.

Use a case-insensitive operator (I_EQUAL_TO, I_CONTAINS, …) unless the casing of your sent values and rule values is guaranteed to match — EQUAL_TO is case-sensitive.

Examples​

Custom Conversions API Examples

Get Pixel Custom Conversions​

Method: GET
Endpoint: {base_url}/pixels/{pixel_id}/custom_conversions

Create A Pixel Custom Conversion​

Method: POST
Endpoint: {base_url}/pixels/{pixel_id}/custom_conversions

Get App Custom Conversions​

Method: GET
Endpoint: {base_url}/mobile_apps/{app_id}/custom_conversions

Create an App Custom Conversion​

Method: POST
Endpoint: {base_url}/mobile_apps/{app_id}/custom_conversions

Get A Custom Conversions​

Method: GET
Endpoint: {base_url}/custom_conversions/{custom_conversion_id}

Delete A Custom Conversions​

Method: DELETE
Endpoint: {base_url}/custom_conversions/{custom_conversion_id}
Was this page helpful?
Yes
No