Custom Conversions

Intro

Custom Conversions enable granular measurement, reporting, and now optimization (open beta) by filtering standard events based on specific parameter values. By defining rules (e.g., 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.

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

Key	Type	Key	Type
event_tag	string	item_id	string
item_category	string	currency	string
search_string	string	sign_up_method	string
page_url	string	category	string
category_id	string	brand	string
delivery_moethod	string	customer_status	string
price	number	number_items	nuber

Custom Conversion Rule Operators

I_* indicates case insensitivity

Rule	Type	Rule	Type
EQUAL_TO	string or number	NOT_EQUAL_TO	string or number
I_CONTAINS	string	I_NOT_CONTAINS	string
CONTAINS	string	NOT_CONTAINS	string
STARTS_WITH	string	I_STARTS_WITH	string
I_EQUAL_TO	string	I_NOT_EQUAL_TO	string
LESS_THAN	number	LESS_THAN_OR_EQUALS	number
GREATER_THAN	number	GREATER_THAN_OR_EQUALS	number

Examples

Custom Conversions API Examples

Get Pixel Custom Conversions

URL

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

Example Response

{
    "request_status": "SUCCESS",
    "request_id": "c33aa2b9-632a-4bf8-978c-c3f51ec911d8",
    "paging": {},
    "custom_conversions": [
        {
            "sub_request_status": "SUCCESS",
            "custom_conversion": {
                "id": "1234567891",
                "event_source": {
                "id": "a9650421-b387-4681-8954-a7c754627df6",
                "type": "PIXEL"
                },
                "name": "Some Conversion Name",
                "description": "Some optional description",
                "event_type": "PURCHASE",
                "rules": [
                {
                    "key": "EVENT_TAG",
                    "values": ["tag-1"],
                    "operator": "I_CONTAINS"
                }
                ]
            }
        }
    ]
}

Create A Pixel Custom Conversion

URL

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

Request

  {
      "custom_conversions": [
          {
          "name": "Some Conversion Name",
          "description": "Some optional description",
          "event_type": "PURCHASE",
          "rules": [
              {
              "key": "EVENT_TAG",
              "values": ["tag-1"],
              "operator": "I_CONTAINS"
              }
          ]
          }
      ]
  }

Example Response

{
    "request_status": "SUCCESS",
    "request_id": "c33aa2b9-632a-4bf8-978c-c3f51ec911d8",
    "custom_conversions": [
        {
        "sub_request_status": "SUCCESS",
        "custom_conversion": {
            "id": "1234567891",
            "event_source": {
            "id": "a9650421-b387-4681-8954-a7c754627df6",
            "type": "PIXEL"
            },
            "name": "Some Conversion Name",
            "description": "Some optional description",
            "event_type": "PURCHASE",
            "rules": [
            {
                "key": "EVENT_TAG",
                "values": ["tag-1"],
                "operator": "I_CONTAINS"
            }
            ]
        }
        }
    ]
 }

Get App Custom Conversions

URL

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

Example Response

{
  "request_status": "SUCCESS",
  "request_id": "c33aa2b9-632a-4bf8-978c-c3f51ec911d8",
  "paging": {},
  "custom_conversions": [
    {
      "sub_request_status": "SUCCESS",
      "custom_conversion": {
        "id": "123456789",
        "event_source": {
          "id": "a9650421-b387-4681-8954-a7c754627df6",
          "type": "MOBILE_APP"
        },
        "name": "Some Conversion Name",
        "description": "Some optional description",
        "event_type": "PURCHASE",
        "rules": [
          {
            "key": "EVENT_TAG",
            "values": ["tag-1"],
            "operator": "I_CONTAINS"
          }
        ]
      }
    }
  ]
}

Create an App Custom Conversion

URL

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

Request

  {
    "custom_conversions": [
      {
        "name": "Some Conversion Name",
        "description": "Some optional description",
        "event_type": "PURCHASE",
        "rules": [
          {
            "key": "EVENT_TAG",
            "values": ["tag-1"],
            "operator": "I_CONTAINS"
          }
        ]
      }
    ]
  }

Example Response

{
  "request_status": "SUCCESS",
  "request_id": "c33aa2b9-632a-4bf8-978c-c3f51ec911d8",
  "custom_conversions": [
    {
      "sub_request_status": "SUCCESS",
      "custom_conversion": {
        "id": "1234567891",
        "event_source": {
          "id": "a9650421-b387-4681-8954-a7c754627df6",
          "type": "MOBILE_APP"
        },
        "name": "Some Conversion Name",
        "description": "Some optional description",
        "event_type": "PURCHASE",
        "rules": [
          {
            "key": "EVENT_TAG",
            "values": ["tag-1"],
            "operator": "I_CONTAINS"
          }
        ]
      }
    }
  ]
}

Get A Custom Conversions

URL

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

Example Response

{
  "request_status": "SUCCESS",
  "request_id": "c33aa2b9-632a-4bf8-978c-c3f51ec911d8",
  "custom_conversions": [
    {
      "sub_request_status": "SUCCESS",
      "custom_conversion": {
        "id": "123456789",
        "event_source": {
          "id": "a9650421-b387-4681-8954-a7c754627df6",
          "type": "PIXEL"
        },
        "name": "Some Conversion Name",
        "description": "Some optional description",
        "event_type": "PURCHASE",
        "rules": [
          {
            "key": "EVENT_TAG",
            "values": ["tag-1"],
            "operator": "I_CONTAINS"
          }
        ]
      }
    }
  ]
}

Delete A Custom Conversions

URL

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

Example Response

{
  "request_status": "SUCCESS",
  "request_id": "c33aa2b9-632a-4bf8-978c-c3f51ec911d8",
  "custom_conversions": []
}