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:

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

To use the API to manage your catalog:

  1. Create a hotel catalog
  2. Create product sets out of your hotel catalog
  3. 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 TypeDescription

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:

  1. On ad level using template_url_spec
  2. Here in the feed using an Applink Object
  3. 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 TypeDescription

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 TypeDescription

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 TypeDescription

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

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

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
'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);
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);
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, )
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(); } }
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'}}, })

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

OperatorsFilter 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.

DataThe 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.