To promote destinations on Facebook, you have to share information about them with Facebook. You do this by creating a destinations catalog and then filling it with destinations.
Upload CSV or XML files for 'destination feeds' with the destinations you want to promote
You can create and manage your destinations catalog in your Commerce Manager.
To use the API to manage your catalog:
A destination feed is a file with the destinations you want to promote. Every line or item in the file represents a single destination. You can use one or more destination feeds, as long as all feeds together contain all destinations you want to promote.
CSV sample | TSV sample (flattened) | TSV sample (JSON-style)
"
double quotes"
. address
, neighborhood
or image
can be represented using JSON-encoded values or by a set of "flattened" plain-text columns labeled using JSON-path syntax, such as address.city
, neighborhood[0]
, image[0].url
, image[0].tag[0]
, image[0].tag[1]
. Both conventions can be used interchangeably in the same file.<listings>
XML node encloses a set of <listing>
nodes, each of which represents a destination.<?xml
declaration tag.The feed parser automatically detects UTF8
, UTF16
, or UTF32
text encodings, and defaults to LATIN1
if it encounters an unexpected byte sequences. You can provide text in field values in any language; however, field names must be given exactly as below, in English.
The following supported fields are designed for items you add to your product catalog.
For localized catalogs, see supported fields for destinations.
Field Name and Type | Description |
---|---|
type: string | Required. Max length: 100 Your unique identifier for the destination within the catalog. This will be matched with any |
type: object | Required. Complete address for the destination that must be resolvable to its location. |
type: object | Required. Max items: 20 Image data for this destination. You can provide up to 20 images for the destination. Each image contains two fields: |
type: string | Required. Link to the external site where you can view the destination page. You can specify a URL on ad level too using |
type: string | Required. Max items: 20 Type of destination, such as beach, city, food, sightseeing, culture, history, shopping, museum, tranquility, scenery, nature, architecture, business, friendly people, relaxation, night market, mountain, temple, hiking, snorkeling, and so on. There can be multiple types associated with a destination; meaning a destination can have multiple attributes, such as |
type: string | Required. Most common name of the destination. |
type: string | Optional. Max items: 20 One or more neighborhood(s) for the destination. Examples: |
type: float | Optional. Latitude of the destination. Example: |
type: float | Optional. Longitude of the destination. Example: |
type: string | Optional. Max size: 5000 Short paragraph describing the destination. |
type: string | Optional. Can be lowest or average price for this destination. You must specify the value with currency. Example: |
type: int | Optional. Price change:
Can be used for building product sets and in the universal creative ("average price dropped by X"). |
type: element | Optional. Deep link straight to the destination details page in your mobile app using App Links. Specify deep links in order of precedence, highest to lowest:
|
Type: string | Controls whether an item is active or archived in your catalog. Only active items can be seen by people in your ads, shops or any other channels. Supported values: Example: Note: Some partner platforms such as Shopify may sync items to your catalog with a status called staging, which behaves the same as This field was previously called |
Provide deep links in feed following the App Links specification. Deep link information in feed takes precedence over any information Facebook collects with App Links metadata with our web crawler.
If you already have deep link information from App Links, you don't need to specify this data. Facebook uses information from App Links to display the correct deep link. To display deep links in your ads, see Advantage+ Catalog Ads, Ad Template.
Field Name and Type | Description |
---|---|
type: string | Required. URL of the destination image. Follow these image specifications:
|
type: string | Optional. String that represents what's in the image. There can be multiple tags associated with an image. Examples:
|
Nested or multi-value fields, such as address
can be represented using JSON-encoded values or by a set of "flattened" plain-text columns labeled using JSON-path syntax, such as address.region
. Both conventions can be used interchangeably in the same file.
Field Name and Type | Description |
---|---|
type: string | Street address of destination. Example: |
type: string | Required. City where destination is located. Example: |
type: string | Required. State, county, region, or province for destination. Example: |
type: string | Postal code or zip code for destination. Required unless country does not have a postal code system. Examples:
|
type: string | Required. Country of the destination. Example: |
type: string | Value to use in deep link URL ( |
If you have separate apps for iPhone and iPad, specify iPhone and iPad specific information. Otherwise specify only iOS information.
Field Name and Type | Description |
---|---|
type: string | A custom scheme for the iOS app. Example: |
type: string | The app ID for the App Store. Example: 1234 |
type: string | The name of the app (suitable for display). Example: |
type: string | A custom scheme for the iPhone app. Example: |
type: string | The app ID for the App Store. Example: |
type:string | The name of the app (suitable for display). Example: |
type: string | A custom scheme for the iPhone app. Example: |
type: string | The app ID for the App Store. Example: |
type: string | The name of the app (suitable for display). Example: |
type: string | A custom scheme for the Android app. Example: |
type: string | A fully-qualified package name for intent generation. Exammple: |
type: string | The name of the app (suitable for display). Example: |
The following sections are only relevant to manage your catalogs using this API.
A destination catalog is a container for the destinations you want to promote. To use the catalog API, make sure you have the appropriate Marketing API Access Level and that you have accepted the Terms of Service by creating your first catalog through Business Manager.
To create a destination catalog for destination ads, set vertical
to destinations
:
curl -X POST \ -F 'name="Test Destination Catalog"' \ -F 'vertical="destinations"' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v10.0/BUSINESS_ID/owned_product_catalogs
Once you have created the catalog, you must upload your destination feed(s) to Facebook. Use the API to create a feed object for every feed you want to upload. We support scheduled and direct uploads.
A destination set is a subset of your catalog. To setup destination ads, you need a destination set. Therefore, you have to create at least one.
Destination sets are defined by filters that are applied to the destination catalog. For example, you can create a destination set with all destinations that had a large price drop. Do note you can also create a destination set without any filters. In that case, the destination set will contain all destinations in your catalog.
use FacebookAds\Object\ProductSet;
use FacebookAds\Object\Fields\ProductSetFields;
$destination_set = new ProductSet(null, <PRODUCT_CATALOG_ID>);
$destination_set->setData(array(
ProductSetFields::NAME => 'Test Destination Set',
ProductSetFields::FILTER => array(
'price_change' => array(
'lt' => -20,
),
),
));
$destination_set->create();
from facebookads.adobjects.productset import ProductSet
destination_set = ProductSet(None, <PRODUCT_CATALOG_ID>)
destination_set[ProductSet.Field.name] = 'Test Destination Set'
destination_set[ProductSet.Field.filter] = {
'price_change': {
'lt': -20,
},
}
destination_set.remote_create()
curl \
-F 'name=Test Destination Set' \
-F 'filter={"price_change":{"lt":-20}}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v2.10/<PRODUCT_CATALOG_ID>/product_sets
The filter
parameter is made up of the following operators and data:
Operators | Filter Type |
---|---|
| Contains substring. Operator is case-insensitive. |
| Does not contain substring. Operator is case-insensitive. |
| Contains substring. Operator is case-insensitive. |
| Does not contain substring. Operator is case-insensitive. |
| Equal to. Operator is case-insensitive. |
| Not equal to. Operator is case-insensitive. |
| Less than. For numeric fields only. |
| Less than or equal to. For numeric fields only. |
| Greater than. For numeric fields only. |
| Greater than or equal to. For numeric fields only. |
Data | The data being filtered |
---|---|
| Country of the destination. |
| Price for this destination. The price is in cents. |
| Currency. |
| Price drop or increase. |
| City of the destination. |
| Description for this destination. |
| Name for this destination. |
| Your unique identifier for the destination within the catalog. |