Custom Audiences from Store Visits

Create a custom audience of users who visited a store. See Custom Audience, Targeting.

Once you create a custom audience with customer store visits data, reference it in ad targeting as you do with standard custom audience. Facebook automatically updates this audience based on the retention policy you setup.

If your business locations are eligible for store visits reporting, and you have at least 10 measurable business locations set up, you can potentially create a Custom Audience based on people on Facebook who have visited your locations.

Store Visit Custom Audiences may not contain all Facebook users that have visited your physical location. Only people that our systems have confidently identified to have visited the location will be present within the audience.

Store Visit Custom Audience Eligibility

Access to the Store Visits Custom Audience Eligibility API endpoint is provided on a whitelist basis only. Please contact your partner manager.

To check if your store location/page is eligible to create Store Visit Audiences use the following API call:

curl -G \
  -d "access_token=<ACCESS_TOKEN>" \
  https://graph.facebook.com/<API_VERSION>/<PARENT_PAGE_ID>/store_visits_custom_audiences_eligible_countries

The call above provides a list of countries that eligible for Store Visits Custom Audiences. The combination of this parent page and each country in this list would be an eligible store visit chain.

Create a Custom Audience

To create a custom audience using this method, the account needs to have already accepted the Terms of Service for Custom Audiences in Ads Manager.

To create a custom audience from your store visits:

curl 
  -F 'name=My Store Visits Custom Audience' 
  -F 'prefill=1' 
  -F 'rule={"inclusions":{"operator":"or","rules":[{"retention_seconds":2592000,"event_sources":[{"id":"<PAGE_ID>","type":"store_visits"}],"filter":{"operator":"and","filters":[{"operator":"=","field":"event","value":"store_visit"},{"operator":"=","field":"store_visit_country","value":"US"}]}}]}}'
  -F 'access_token=ACCESS_TOKEN' 
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

This returns the id of the audience upon success. These parameters are most relevant for custom audiences based on your customer visits in your store:

Name Description Type Required

name

Name of the cluster

String

Yes

description

Description of the cluster

String

No

rule

Audience rules to be applied on the referrer URL.


Note: Store Visit Custom Audience rule syntax differs from other Custom Audience endpoints prior to v2.11. See the Audience Rules section.

String

Yes

prefill

true—Includes website traffic recorded prior to the audience creation.


false—Only includes website traffic beginning at the time of the audience creation.

Boolean

No

Audience Rules

Some key components of Audiences rules are:

For for full examples of these components in action see "Example Custom Audience Rules"

Audience Rule Syntax

To define an audience rule, the following structure must be followed:

rule : {
    inclusions: <RULE_SET>,
    exclusions: <RULE_SET>,
}
Name Description Type Required

inclusions

Rule Set JSON string that will define the inclusion

String

Yes

exclusions

Rule Set JSON string that will define the exclusion

String

No

A custom audience for Store Visits Custom Audiences must contain an audience rule. Each rule must be provided as a JSON-encoded string.

Rule Set Syntax

{
"operator" : <BOOLEAN_OPERATOR>,
"rules" : <JSON_RULE>,
}
Name Description Type Required

operator

and or or

String

Yes

rules

JSON string of rules (array of rules)

String

Yes

Inclusion/Exclusion Rule Syntax

{
  "event_sources" : <EVENT_SOURCE_DEFINITION>, 
  "retention_seconds" : <SECONDS>,
  "filter" : <FILTER>,
  "aggregation" : <AGGREGATION>, 
}

The aggregation and retention_seconds are editable fields. However, editing aggregation and retention_seconds won't flush the audience. People who only match the old rule/aggregation continue to be in the audience until they expire.

Name Description Type Required

event_sources

JSON object containing the

  • id: Page ID of the store
  • type: store_visits

More event sources can be added to the type using a comma delimited list "store_visits,pixel,app"

String

Yes

retention_seconds

Integer in seconds for the retention window of the audience

Integer

Yes

filter

JSON string or the filter rules


See more in "Filters"

String

No

aggregation

JSON string of the aggregation rule


See more in "Aggregate Functions"

Integer

No

Filters

Filtration follows this general format:

"filter" : {
   "operator": <BOOLEAN_OPERATOR>,
   "filters": <FILTER_SET>,
}
Name Description Type Required

operator

and or or

String

Yes

filters

Array of JSON objects of filter rules

String

Yes

Filter Rules

{
  "operator": "=",
  "field": "event",
  "value": "store_visit"
}

Filter rules are made up the following fields:

Name Description

operator

  • =
  • >
  • >=
  • <
  • <=
  • !=

field

event or store_visit_country

value

  • if the field attribute is set to event the value must be set to store_visit
  • if the field attribute is set to store_visit_country the value must be set to two letter ISO country code (e.g. US)

Aggregate Functions

Create custom audiences based upon the frequency and intensity of behavior using the aggregation in the audience rule field. With this, you define an aggregate function. For example:

"aggregation" : {
  "type":"count",
  "operator":">",
  "value":1
}

Aggregation rules are made up the following fields:

Name Description

type

The type of the aggregation function: count

config

Required by certain types of aggregation functions.

operator

  • =
  • >
  • >=
  • <
  • <=
  • !=

value

Integer

The available functions are:

Name Required Config Description

count

Number of store visits that satisfy the rule

Example Custom Audience Rules

Rule Description
{
  "inclusions": {
    "operator": "or",
    "rules": [
      {
        "retention_seconds": 2592000,
        "event_sources": [
          {
            "id": "<PAGE_ID>",
            "type": "store_visits"
          }
        ],
        "filter": {
          "operator": "and",
          "filters": [
            {
              "operator": "=",
              "field": "event",
              "value": "store_visit"
            },
            {
              "operator": "=",
              "field": "store_visit_country",
              "value": "US"
            }
          ]
        }
      }
    ]
  }
}

Customers visited your store in the last 30 days in the US.

{
  "inclusions": {
    "operator": "or",
    "rules": [
      {
        "retention_seconds": 2592000,
        "event_sources": [
          {
            "id": "<PAGE_ID>",
            "type": "store_visits"
          }
        ],
        "filter": {
          "operator": "and",
          "filters": [
            {
              "operator": "=",
              "field": "event",
              "value": "store_visit"
            },
            {
              "operator": "=",
              "field": "store_visit_country",
              "value": "US"
            }
          ]
        },
        "aggregation": {
          "type": "count",
          "operator": ">",
          "value": 1
        }
      }
    ]
  }
}

Aggregation Example: Customers visited your store in the last 30 days more than one time in the US.

{
    "inclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "id": "<PAGE_ID>",
                        "type":"store_visits"
                    }
                ],
                "retention_seconds": 2592000,
                "filter": {
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "store_visit"
                        }
                    ]
                }
            }
        ]
    },
    "exclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "id": "<PAGE_ID>",
                        "type": "store_visits"
                    }
                ],
                "retention_seconds": 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "store_visit"
                        },
                        {

                           "field": "store_visit_country",
                           "operator": "=",
                           "value": "US"

                        }
                    ]
                }
            },
            {
                "event_sources": [
                    {
                        "id": "<PAGE_ID>",
                        "type": "store_visits"
                    }
                ],
                "retention_seconds": 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "store_visit"
                        },
                        {

                            "field": "store_visit_country",
                            "operator": "=",
                             "value": "GB"
                        }
                    ]
                }
            }
        ]
    }
}

Exclusion Example: All Customers who visited your store excluding US and UK customers.