Custom Conversions

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": []
}