Hotel Ads - Catalogs & Feed

To promote your hotel inventory on Facebook, you have to share information about your hotels with Facebook. You do this by creating a hotel catalog and then filling it with hotels. There are 2 ways you can fill your catalog and update it:

Upload CSV or XML files for hotel feeds with your hotel inventory
Create and manage hotels directly in API

You can create and manage your hotel catalogs in your Commerce Manager.

To use the API to manage your catalog:

Create a hotel catalog
Create product sets out of your hotel catalog
Associate the catalog to your event sources

Hotel Feeds - Upload Your Hotels to Facebook

A hotel feed is a file with your hotel inventory. Every line or item in the file represents a single hotel. You can use one or more hotel feeds, as long as all feeds together contain your full hotel inventory.

Supported Hotel Feed Formats

CSV

CSV sample | TSV sample (flattened) | TSV sample (JSON style)

The first row must list the chosen field names in the order the values are given. Subsequent rows then supply the corresponding values for each hotel.
Fields containing whitespace or commas should be enclosed in "double quotes".
Nested or multi-value fields, such as 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.

XML

XML sample

A root <listings> XML node encloses a set of <listing> nodes, each of which represents a hotel.
The file must begin with a valid <?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.

Supported Fields — Hotel Ads

The following supported fields are designed for items you add to your product catalog.

For localized catalogs, see supported fields for hotel ads.

Field and Type Description

Field and Type	Description
`hotel_id` type: string	Required. Max length: 100 Your unique identifier for the hotel within the catalog. This ID is matched with any `content_ids` provided in your `hotel` app and pixel events. Tip: To improve performance, avoid using a space for this unique identifier field. Don't use duplicate IDs. Example: `FB_hotel_1234`
`room_id` type: string	Required if adding hotel room information. Enter a unique ID for the hotel room type. Max characters: 100 Example: `FB_hotel_room_1234`
`name` type: string	Required. Most common name of the hotel. Example: `Facebook Hotel`
`description` type: string	Required. Max size: 5000 Brief description of the hotel. Example: `Only 30 minutes away from San Francisco.`
`checkin_date` type: string	Required if adding hotel room information. Check-in date for the hotel stay. You can add up to 180 days from the date the feed is uploaded. Uses ISO-8601 standard (`YYYY-MM-DD`). Example: `2017-08-01`
`length_of_stay` type: string	Required if adding hotel room information. Number of nights for the hotel stay. Example: `7`
`base_price` type: string	Required if adding hotel room information. Base price of the hotel room per night. Make sure to add the currency type to the price (for example, USD for U.S. dollars). Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: `199.00 EUR`
`price` type: string	Required if adding hotel room information. Total price of the hotel stay, based on `checkin_date` and `length_of_stay`. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: `1393.00 USD`
`tax` type: string	Required if adding hotel room information. Applicable tax rate for the price. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: `14.00 USD`
`fees` type: string	Required if adding hotel room information. Applicable fees for the price. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: `253.00 USD`
`url` type: string	Required. Link to the external site where you can book a hotel room. You can also specify a URL on ad level using `template_url_spec`. URLs on the ad level take precedence over URLs in the feed. Example: `https://www.facebook.com/hotel`
`image[0].url` type: object	See Image Object Parameters.
`image[0].tag` type: object	See Image Object Parameters.
`brand` type: string	Required. Brand name of the hotel chain. Example: `Hilton`
`address` type: object	See Address Object Parameters.
`neighborhood[0]` type: string	Required. Max neighborhoods allowed: 20 Neighborhood where the hotel is located. If there's more than one neighborhood, add additional columns for each one and use JSON-path syntax in each column name to indicate the number of neighborhoods. Example: `Belle Haven`
`latitude` type: float	Required. Latitude of the hotel. Example: `37.484100`
`longitude` type: float	Required. Longitude of the hotel. Example: `-122.148252`
`sale_price` type: string	Optional. Sale price per night of hotel stay, based on `checkin_date` and `length_of_stay`. Use this when you want to advertise discounts off the regular price of the hotel. Make sure to add the currency type to the price (for example, USD for U.S. dollars).Make sure the `sale_price` of a hotel is lower than its `base_price`. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: `149.00 USD`
`guest_ratings.score` type: object	See Guest Rating Object Parameters.
`guest_ratings.rating_system` type: object	See Guest Rating Object Parameters.
`star_rating` type: float	See Guest Rating Object Parameters.
`loyalty_program` type: string	Optional. Loyalty program you use to gain points for staying at the hotel. Example: `Premium program`
`margin_level` type: integer	Optional. Indicator of the profitability of the hotel; value from 1 to 10. Example: `9`
`phone` type: string	Optional. Primary phone number for the hotel. Example: `+61 296027455`
`applink` type: object	Optional. Deep link straight to the hotel details page in your mobile app using App Links. You can specify deep links in order of precedence, highest to lowest: On ad level using `template_url_spec` Here in the feed using an Applink Object By adding App Link meta tags to your website. Learn more about product deep links.
`priority` type: integer	Optional. An indicator of the priority of the hotel; value from 0(lowest priority) to 5(highest priority). Example: `5`
`category` type: string	Optional. The type of property. The category can be any type of internal description desired. Example: `Resort`, `Day Room`
`number_of_rooms` type: integer	Optional. Total number of rooms/units in this hotel listing. Example: `150`
`status` 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: `active`, `archived`. Items are active by default. Learn more about archiving items. Example: `active` Note: Some partner platforms such as Shopify may sync items to your catalog with a status called staging, which behaves the same as `archived`. This field was previously called `visibility`. While we still support the old field name, we recommend that you use the new name.
`custom_label_0` `custom_label_1` `custom_label_2` `custom_label_3` `custom_label_4` Type: string	Max character limit: 100 Up to five custom fields for any additional information you want to filter items by when you create sets. For example, you could use a custom field to indicate all rooms that are part of a summer sale, and then filter those items into a set. This field supports any text value, including numbers. Example: `Summer Sale` This field is supported by supplementary feeds.
`custom_number_0` `custom_number_1` `custom_number_2` `custom_number_3` `custom_number_4` Type: int	Up to five custom fields for any additional number-related information you want to filter items by when you create sets. This field allows you to filter by number ranges (is greater than and is less than) when you create a set. For example, you could use this field to indicate the year a hotel was opened, and then filter a certain year range into a set. This field supports whole numbers between 0 and 4294967295. It doesn't support negative numbers, decimal numbers or commas, such as -2, 5.5 or 10,000. Example: `2022`

hotel_id

type: string

Required.

Max length: 100

Your unique identifier for the hotel within the catalog. This ID is matched with any content_ids provided in your hotel app and pixel events. Tip: To improve performance, avoid using a space for this unique identifier field. Don't use duplicate IDs.

Example: FB_hotel_1234

room_id

type: string

Required if adding hotel room information.

Enter a unique ID for the hotel room type. Max characters: 100 Example: FB_hotel_room_1234

name

type: string

Required.

Most common name of the hotel.

Example: Facebook Hotel

description

type: string

Required.

Max size: 5000

Brief description of the hotel.

Example: Only 30 minutes away from San Francisco.

checkin_date

type: string

Required if adding hotel room information.

Check-in date for the hotel stay. You can add up to 180 days from the date the feed is uploaded. Uses ISO-8601 standard (YYYY-MM-DD).

Example: 2017-08-01

length_of_stay

type: string

Required if adding hotel room information.

Number of nights for the hotel stay.

Example: 7

base_price

type: string

Required if adding hotel room information.

Base price of the hotel room per night. Make sure to add the currency type to the price (for example, USD for U.S. dollars). Format price as the cost, followed by the ISO currency code, with a space between cost and currency.

Example: 199.00 EUR

price

type: string

Required if adding hotel room information.

Total price of the hotel stay, based on checkin_date and length_of_stay. Format price as the cost, followed by the ISO currency code, with a space between cost and currency.

Example: 1393.00 USD

tax

type: string

Required if adding hotel room information.

Applicable tax rate for the price. Format price as the cost, followed by the ISO currency code, with a space between cost and currency.

Example: 14.00 USD

fees

type: string

Required if adding hotel room information.

Applicable fees for the price. Format price as the cost, followed by the ISO currency code, with a space between cost and currency.

Example: 253.00 USD

url

type: string

Required.

Link to the external site where you can book a hotel room. You can also specify a URL on ad level using template_url_spec. URLs on the ad level take precedence over URLs in the feed.

Example: https://www.facebook.com/hotel

image[0].url

type: object

See Image Object Parameters.

image[0].tag

type: object

See Image Object Parameters.

brand

type: string

Required.

Brand name of the hotel chain.

Example: Hilton

address

type: object

See Address Object Parameters.

neighborhood[0]

type: string

Required.

Max neighborhoods allowed: 20

Neighborhood where the hotel is located. If there's more than one neighborhood, add additional columns for each one and use JSON-path syntax in each column name to indicate the number of neighborhoods.

Example: Belle Haven

latitude

type: float

Required.

Latitude of the hotel.

Example: 37.484100

longitude

type: float

Required.

Longitude of the hotel.

Example: -122.148252

sale_price

type: string

Optional.

Sale price per night of hotel stay, based on checkin_date and length_of_stay. Use this when you want to advertise discounts off the regular price of the hotel. Make sure to add the currency type to the price (for example, USD for U.S. dollars).Make sure the sale_price of a hotel is lower than its base_price. Format price as the cost, followed by the ISO currency code, with a space between cost and currency.

Example: 149.00 USD

guest_ratings.score

type: object

See Guest Rating Object Parameters.

guest_ratings.rating_system

type: object

See Guest Rating Object Parameters.

star_rating

type: float

See Guest Rating Object Parameters.

loyalty_program

type: string

Optional.

Loyalty program you use to gain points for staying at the hotel.

Example: Premium program

margin_level

type: integer

Optional.

Indicator of the profitability of the hotel; value from 1 to 10.

Example: 9

phone

type: string

Optional.

Primary phone number for the hotel.

Example: +61 296027455

applink

type: object

Optional.

Deep link straight to the hotel details page in your mobile app using App Links. You can specify deep links in order of precedence, highest to lowest:

On ad level using template_url_spec
Here in the feed using an Applink Object
By adding App Link meta tags to your website.

Learn more about product deep links.

priority

type: integer

Optional.

An indicator of the priority of the hotel; value from 0(lowest priority) to 5(highest priority). Example: 5

category

type: string

Optional.

The type of property. The category can be any type of internal description desired. Example: Resort, Day Room

number_of_rooms

type: integer

Optional.

Total number of rooms/units in this hotel listing.

Example: 150

status

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: active, archived. Items are active by default. Learn more about archiving items.

Example: active

Note: Some partner platforms such as Shopify may sync items to your catalog with a status called staging, which behaves the same as archived.

This field was previously called visibility. While we still support the old field name, we recommend that you use the new name.

custom_label_0
custom_label_1
custom_label_2
custom_label_3
custom_label_4

Type: string

Max character limit: 100

Up to five custom fields for any additional information you want to filter items by when you create sets. For example, you could use a custom field to indicate all rooms that are part of a summer sale, and then filter those items into a set. This field supports any text value, including numbers.

Example: Summer Sale

This field is supported by supplementary feeds.

custom_number_0
custom_number_1
custom_number_2
custom_number_3
custom_number_4

Type: int

Up to five custom fields for any additional number-related information you want to filter items by when you create sets. This field allows you to filter by number ranges (is greater than and is less than) when you create a set. For example, you could use this field to indicate the year a hotel was opened, and then filter a certain year range into a set.

This field supports whole numbers between 0 and 4294967295. It doesn't support negative numbers, decimal numbers or commas, such as -2, 5.5 or 10,000.

Example: 2022

Image Object Parameters

Field Name and Type Description

Field Name and Type	Description
`url` type: string	Required. Max items: 20. URL link to the image of the item that will appear in your ads. Follow these image specifications: All images must be in JPG, GIF, or PNG format. For carousel ads and collection ads: Images display in square (1:1) format. The minimum image size is 500 x 500 px. We recommend 1024 x 1024 px for best quality. For single image ads: Images display at a 1.91:1 aspect ratio. The minimum image size is 500 x 500 px. We recommend 1200 x 628 px for best quality. If you have more than one image, add additional columns for each one and use JSON-path syntax in each column name to indicate the number of images. Example: `image[0].url; image[1].url` Example: `https://www.facebook.com/facebook_hotel.jpg`
`tag` type: string	Optional. Tag appended to the image that shows what's in the image. There can be multiple tags associated with an image. Examples: `Fitness Center`, `Swimming Pool`, `suite` `INSTAGRAM_STANDARD_PREFERRED` - Allows advertisers to tag a specific image in their feed as the default image to use for Instagram. This tag is case-sensitive.

url

type: string

Required.

Max items: 20.

URL link to the image of the item that will appear in your ads. Follow these image specifications:

All images must be in JPG, GIF, or PNG format.
For carousel ads and collection ads: Images display in square (1:1) format. The minimum image size is 500 x 500 px. We recommend 1024 x 1024 px for best quality.
For single image ads: Images display at a 1.91:1 aspect ratio. The minimum image size is 500 x 500 px. We recommend 1200 x 628 px for best quality.
If you have more than one image, add additional columns for each one and use JSON-path syntax in each column name to indicate the number of images.

Example: image[0].url; image[1].url

Example: https://www.facebook.com/facebook_hotel.jpg

tag

type: string

Optional.

Tag appended to the image that shows what's in the image. There can be multiple tags associated with an image.

Examples: Fitness Center, Swimming Pool, suite

INSTAGRAM_STANDARD_PREFERRED - Allows advertisers to tag a specific image in their feed as the default image to use for Instagram. This tag is case-sensitive.

Address Object Parameters

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

Field Name and Type	Description
`addr1` (`address.addr1`) type: object	Required. Primary street address of hotel. Example: `1600 Pennsylvania Avenue`
`address.addr2` type: object	Optional. The secondary street address of the hotel. Example: `Apartment 1`
`address.addr3` type: object	Optional. The tertiary street address of the hotel. Example: `Downstairs`
`address.city_id` (`city_id`) type: string	Optional. Value to use in deep link URL, `template_url`, in ad creative. Example: `12345`
`address.city` (`city`) type: string	Required. City where the hotel is located. Example: `New York`
`address.region` (`region`) type: string	Required. State, county, province, where the hotel is located. Example: `California`
`address.country` (`country`) type: string	Required. Country where the hotel is located. Example: `United States`
`address.postal_code` (`postal_code`) type: string	Required for countries with a postal code system. Postal or zip code of the hotel. Examples: `94125`, `NW1 3FG`

addr1 (address.addr1)

type: object

Required.

Primary street address of hotel.

Example: 1600 Pennsylvania Avenue

address.addr2

type: object

Optional.

The secondary street address of the hotel.

Example: Apartment 1

address.addr3

type: object

Optional.

The tertiary street address of the hotel.

Example: Downstairs

address.city_id (city_id)

type: string

Optional.

Value to use in deep link URL, template_url, in ad creative.

Example: 12345

address.city (city)

type: string

Required.

City where the hotel is located.

Example: New York

address.region (region)

type: string

Required.

State, county, province, where the hotel is located.

Example: California

address.country (country)

type: string

Required.

Country where the hotel is located.

Example: United States

address.postal_code (postal_code)

type: string

Required for countries with a postal code system.

Postal or zip code of the hotel.

Examples: 94125, NW1 3FG

Guest Rating Object Parameters

Field Name and Type Description

Field Name and Type	Description
`guest_ratings.score` (`score`) type: object	Optional. Total number of people who have reviewed your hotel. If specified, you must also provide `score`, `max_score`, `number_of_reviewers` and `rating_system`. Example: `9.0/10`
`guest_ratings.number_of_reviewers` (`number_of_reviewers`) type: int	Optional. Total number of people who have rated this hotel. Example: `5287`
`guest_ratings.rating_system` (`rating_system`) type: string	Optional. System you use for guest reviews. Examples: `Expedia`, `TripAdvisor`
`max_score` type: int	Required. Max value for the hotel rating score. Must be greater than or equal to 0, and less than or equal to 100. Example: `10`

guest_ratings.score (score)

type: object

Optional.

Total number of people who have reviewed your hotel. If specified, you must also provide score, max_score, number_of_reviewers and rating_system.

Example: 9.0/10

guest_ratings.number_of_reviewers (number_of_reviewers) type: int

Optional.

Total number of people who have rated this hotel.

Example: 5287

guest_ratings.rating_system (rating_system)

type: string

Optional.

System you use for guest reviews.

Examples: Expedia, TripAdvisor

max_score

type: int

Required.

Max value for the hotel rating score. Must be greater than or equal to 0, and less than or equal to 100.

Example: 10

Hotel API - Create and Manage Hotels Directly

You can use the Hotel API to directly add, edit, and remove hotels in your catalog. Use the Hotel API Reference for more information on how to manage hotels using the API.

The following sections are only relevant to manage your catalogs using this API.

Create a Hotel Catalog Using the API

Reference Docs

Product Catalog Reference

A hotel catalog is a container for your hotel inventory. 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 hotel catalog for hotel ads, set vertical to hotels:

curl -X POST \
  -F 'name="Test Hotel Catalog"' \
  -F 'vertical="hotels"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v10.0/BUSINESS_ID/owned_product_catalogs

Upload Your Hotel Feeds via the API

Once you've created the catalog, you must upload your hotel 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.

Filter Hotel Catalog to Hotel Sets

Reference Docs

Product Set Reference

A hotel set is a subset of your catalog. To set up hotel ads, you need a hotel set. Therefore, you need to create at least one.

Hotel sets are defined by filters that are applied to the hotel catalog. For example, you can create a hotel set with all hotels with a star_rating greater than 3. Note: You can also create a hotel set without any filters. In that case, the hotel set will contain all hotels in your catalog.

To create a hotel set containing all the hotels that contain 'sample brand' mentioned in the brand field:


curl -X POST \
  -F 'name="Test Hotel Set"' \
  -F 'filter={
       "brand": {
         "i_contains": "sample brand"
       }
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<PRODUCT_CATALOG_ID>/product_sets

Open In Graph API Explorer


'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const ProductCatalog = bizSdk.ProductCatalog;
const ProductSet = bizSdk.ProductSet;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<PRODUCT_CATALOG_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'Test Hotel Set',
  'filter' : {'brand':{'i_contains':'sample brand'}},
};
const product_sets = (new ProductCatalog(id)).createProductSet(
  fields,
  params
);
logApiCallResult('product_sets api call complete.', product_sets);

Open In Graph API Explorer


require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\ProductCatalog;
use FacebookAds\Object\ProductSet;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<PRODUCT_CATALOG_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'Test Hotel Set',
  'filter' => array('brand' => array('i_contains' => 'sample brand')),
);
echo json_encode((new ProductCatalog($id))->createProductSet(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);

Open In Graph API Explorer

View on GitHub


from facebook_business.adobjects.productcatalog import ProductCatalog
from facebook_business.adobjects.productset import ProductSet
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<PRODUCT_CATALOG_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'Test Hotel Set',
  'filter': {'brand':{'i_contains':'sample brand'}},
}
print ProductCatalog(id).create_product_set(
  fields=fields,
  params=params,
)

Open In Graph API Explorer

View on GitHub


import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<PRODUCT_CATALOG_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new ProductCatalog(id, context).createProductSet()
      .setName(\"Test Hotel Set\")
      .setFilter(\"{\\"brand\\":{\\"i_contains\\":\\"sample brand\\"}}\")
      .execute();

  }
}

Open In Graph API Explorer

View on GitHub


require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<PRODUCT_CATALOG_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

product_catalog = FacebookAds::ProductCatalog.get(id)
product_sets = product_catalog.product_sets.create({
    name: 'Test Hotel Set',
    filter: {'brand':{'i_contains':'sample brand'}},
})

Open In Graph API Explorer

View on GitHub

The filter parameter is made up of the following operators and data:

Operators	Filter Type
`i_contains`	Contains substring. Operator is case-insensitive.
`i_not_contains`	Does not contain substring. Operator is case-insensitive.
`contains`	Contains substring. Operator is case-insensitive.
`not_contains`	Does not contain substring. Operator is case-insensitive.
`eq`	Equal to. Operator is case-insensitive.
`neq`	Not equal to. Operator is case-insensitive.
`lt`	Less than. For numeric fields only.
`lte`	Less than or equal to. For numeric fields only.
`gt`	Greater than. For numeric fields only.
`gte`	Greater than or equal to. For numeric fields only.

Data	The data being filtered.
`hotel_id`	Your unique identifier for the hotel within the catalog.
`brand`	Brand of the hotel chain.
`base_price_amount`	Base price per night for this hotel. The price is in cents (4999 denotes $49.99).
`sale_price_amount`	Sale price per night for this hotel. The price is in cents (4999 denotes $49.99).
`currency`	Currency
`city`	City where hotel is located.
`country`	Country of the hotel.
`name`	The most common name of the hotel.
`star_rating`	Hotel star rating. The valid values are between 1 to 5 and should be a multiple of 0.5.