When posting to this edge, no Graph object will be created.
Use this endpoint to create, delete or update multiple items in a Catalog at a time.
The sample API call illustrates how this API works in practice.
Limitations
The requests parameter can contain up to 5000 items. It is recommended that the request size be kept under 3000 records for optimal performance.
The request payload size should not exceed 28 MB.
For each catalog, you can make a number of calls per minute defined by the Catalog Batch business use case rate limit formula. If that's not sufficient, please contact us.
Parameters
Parameter
Description
allow_upsert boolean
Default value: true
Set this to true if you want to allow requests with method=UPDATE to create new items.
When set to false, update requests for items not existing in the catalog will not be completed.
The type of items in the request. Needs to be one of the values listed here. Note that the information specified in this field is NOT a product category (a concept used for item_type=PRODUCT_ITEM).
required
requests JSON object
The string should be a JSON array with no more than 5000 records. It is recommended that the request size be kept under 3000 records for optimal performance. Each record should contain 2 fields:
method: one of CREATE/UPDATE/DELETE
data: a map containing catalog item field names and the corresponding values.
When the method is CREATE, this object must contain all the required fields for the specified item_type.
When the method is UPDATE, it can contain any fields.
A request with method=DELETE is expected to contain only the fields that are necessary to identify an item (see below)
Note: see Supported Fields for details on what can be specified for a catalog item.
The Sample Call below demonstrates how the ‘request’ parameter can be passed.
required
Return Type
This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
handles: List [string],
validation_status: List [ Struct {
errors: List [ Struct {
message: string,
}],
retailer_id: string,
warnings: List [ Struct {
message: string,
}],
}],
}
Error Codes
Error Code
Description
80014
There have been too many calls for the batch uploads to this catalog account. Wait a bit and try again. For more info, please refer to /docs/graph-api/overview/rate-limiting#catalog.
100
Invalid parameter
200
Permissions error
190
Invalid OAuth 2.0 Access Token
Updating
You can't perform this operation on this endpoint.
Deleting
You can't perform this operation on this endpoint.
Response Payload Specification
For a Successful Call
Field
Description
handles
An array of strings, containing either 0 or 1 value. An empty array means that nothing has been ingested. The handle returned here can be used to check the status of the submitted request via the /check_batch_request_status API endpoint.
validation_status
An array of ValidationStatus objects (see below)
A ValidationStatus object has the following fields:
Field
Description
retailer_id
Row identifier from one of the records in the ‘requests’ parameter
errors
An array of Error objects (see below)
warnings
An array of Error objects (see below)
An Error object has the following structure
Field
Description
message
A human-readable string providing an explanation of what is the issue with provided product data.
Fields that can be passed for items, depending on type
item_type=PRODUCT_ITEM
↳
Field
Description
additional_image_link
type: array< string >
Optional.
A JSON-array containing up to 50 image URLs.
additional_variant_attribute
type: string
Optional.
Additional attributes to distinguish the product in its variant group. A comma-separated list of attribute+value pairs where the attribute name and its value are separated by a colon symbol (‘:’)
Example: "Scent:Fruity,Flavor:Apple"
age_group
type: string
Optional.
Group of people who are the same age or a similar age. Accepted values are newborn, infant, toddler, kids, adult.
applink
type: object< string >
Optional.
Links to mobile apps. A JSON object with string keys and string values. The following keys are supported:
ios_url
ios_app_store_id
ios_app_name
iphone_url
iphone_app_store_id
iphone_app_name
ipad_url
ipad_app_store_id
ipad_app_name
android_url
android_package
android_class
android_app_name
windows_phone_url
windows_phone_app_id
windows_phone_app_name
availability
type: string
Required.
Identifies availability status:
in stock - Item ships immediately
out of stock - No plan to restock
available for order - Ships in 1–2 weeks
discontinued
brand
type: string
Required.
Brand of the item.
color
type: string
Optional.
Max size: 100.
Item color.
condition
type: string
Required.
Product condition: new, refurbished, or used.
custom_label_0
custom_label_1
custom_label_2
custom_label_3
custom_label_4
type: string
Optional.
Max character limit: 100
Additional information about item.
custom_number_0
custom_number_1
custom_number_2
custom_number_3
custom_number_4
type: integer
Optional.
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
description
type: string
Required.
Max size: 5000.
Short text describing product.
disabled_capabilities
type: array< string >
Optional.
List of capabilities to be disabled. Possible values are: marketplace, b2c_marketplace, buy_on_facebook, cpas_parent_catalog, marketplace_shops, shops, daily_deals, ig_onsite_shopping, ig_product_tagging, c2c_marketplace, groups, profile, da, whatsapp, ldp, mini_shops, business_inbox_in_messenger, neighborhoods, test_capability.
fb_product_category
type: string
Optional.
Provide the most specific Facebook product category possible from this list: Spreadsheet (.csv) or Plain text (.txt). Enter either the category name (not case sensitive) or its ID number.
Global Trade Item Number (GTIN) can include UPC, EAN, JAN, and ISBN.
expiration_date
type: date
Optional.
Product expiration. If the product has expired, it won’t be shown on Facebook. This date should follow the ISO‑8601 (YYYY‑MM‑DD) format.
id
type: string
Required.
Character limit: 100
A unique content ID for the item. Use the item’s SKU if you can.
Each content ID must appear only once in your catalog. To run
dynamic ads this ID must exactly match the content ID for
the same item in your Facebook pixel code.
image
type: array< object >
Required.
URLs and tags for images to be used in your ads or in shops.
A JSON array containing up to 21 records with the following fields:
url: the URL string of the image
tag: a JSON array of strings. Tags are optional and, if used, should describe what is in the image.
image_link
type: string
Optional.
Not required if image is provided.
We recommend using image instead. When image is provided, image_link and additional_image_link are ignored.
Link to item image used in the ad. Provide proper image sizes.
For single-image Advantage+ catalog ads:
Min image resolution requirement is 500px*500px.
Min aspect ratio requirement is 4:5.
Max aspect ratio requirement is 1:91:1. If the image is outside this aspect ratio, Facebook crops it to be closest to either the minimum aspect ratio or the maximum aspect ratio, depending on its original aspect ratio.
For carousel image, Advantage+ catalog ads: Min image resolution requirement is 500px*500px, and Facebook crops it to a 1:1 aspect ratio.
importer_address
type: JSON structure
Optional.
If the country of origin is not India, provide the operational address of the importer. This field uses a JSON structure, which contains the following fields:
street1 - string, required. The first line of the street address
street2 - string, optional. The second line of the street address.
city - string, required. The city name.
region - string, optional. The region, state or province. (In the US this is to be used for US State)
postal_code - string, optional (in the US this is to be used for Zip Code)
country - required. Enter the ISO Country code (2-letter country code)
The overall address will be displayed to users in the following format: street1, street2 (if present), city, region (if present) postal_code (if present), country (full name, localized for the user).
will be rendered as “1 Hacker Way, Building 18, Menlo Park, CA 94025 United States of America”
importer_name
type: string
Optional.
If the country of origin is not India, provide the legal entity name of the item’s importer
Example value: Jasper's Market Inc.
internal_label
type: array< string >
Optional.
Add internal labels to help filter items when you create product sets. For example, you could add a “summer” label to all items that are part of a summer promotion and then filter those items into a set. Labels are only visible to you
Character limit: Up to 5,000 labels per product and 110 characters per label.
Example ['summer','trending']
Note: If you’re currently using custom labels (custom_label_0 to custom_label_4) for filtering product sets, switching to internal labels (internal_label) instead is recommended. Unlike custom labels, you can add or update internal labels as often as needed without sending items through policy review each time, which can impact ad delivery.
This field was previously called product_tags. While we still support the old field name, we recommend that you use the new name.
mobile_link
type: string
Optional.
Link to a mobile-optimized page for the item on the merchant’s website.
quantity_to_sell_on_facebook
type: integer
Optional.
The quantity of this item you have to sell on Facebook and Instagram with checkout. Must be 1 or higher or the item won’t be buyable.
NOTE: The quantity_to_sell_on_facebook field is replacing the inventory field, which is being deprecated. While we will support the old field name in the near term, we recommend that you use the new name.
item_group_id
type: string
Optional.
The advertiser-supplied ID of a product group; not the FBID. Accepts strings. Can be used by advertisers to group a variety of different objects (product items, vehicles, hotels, flights, and so on together.
link
type: string
Required.
Link to merchant’s site where someone can buy the item.
material
type: string
Optional.
Character limit: 200.
The material the item is made from, such as cotton, denim or leather.
mpn
type: string
Optional.
Unique manufacturer ID for product.
ordering_index
type: integer
Optional.
Zero-based index used for ordering items within a group.
Example value: 0
origin_country
type: ISO 3166-1 alpha-2 (2 letter country code)
Optional.
The item’s country of origin. Enter the two-letter ISO country code
Example value: US
pattern
type: string
Optional.
Max size: 100.
Pattern or graphic print on a product.
price
type: string
Required.
Price of the item. Format price as the cost, followed by the 3-digit ISO currency code, with a space between cost and currency.
The number of ratings purchasers have provided for this product. Must be greater than 0. This should be used in conjunction with user_rating.
Example: 100
rich_text_description
type: string
Optional.
A description of the item containing rich text (HTML) formatting such as bullet points or multiple paragraphs. We recommend using rich text if the description is longer than 200 characters to help make it easier to read. If this field is provided, it will be displayed instead of the description field wherever possible, but you must still provide description as a backup option. Character limit: 9,999.
Supported HTML tags: html, form, fieldset, div, span
Other formatting tags: p, b, u, i, em, strong, title, small, br, div, sub, sup, pre, q, s
Note: <script> and <style> tags aren’t supported. If you include them, they’ll be automatically removed.
Example: <html><p>A comfortable royal blue women's T-shirt in organic cotton. Cap sleeves and relaxed fit. Perfect for warm summer days. Features graphic print of logo in white on upper left sleeve.</p> <ul> <li>100% organic cotton</li><li>Machine wash, tumble dry low</li> </ul> </html>
sale_price
type: string
Optional.
Discounted price if the item is on sale. Format price as the cost, followed by the 3-digit ISO currency code, with a space between cost and currency.
Examples: 9.99 USD, 25.00 EUR
sale_price_effective_date
type: string
Optional.
Start and end date and time for the sale, separated by a slash. Write the start and end dates as YYYY-MM-DD. Add a “T” after each date and then include the time. Write the time in a 24-hour format (0:00 to 23:59).
The comma- and colon-separated format (US:CA:Ground:9.99 USD, US:NY:Air:15.99 USD) is discouraged but is also supported
shipping_weight
type: string
Shipping weight of the item in lb, oz, g, or kg.
Example: 10 kg
size
type: string
Optional.
Size of item. Example: Small or XL.aasasd
title
type: string
Required.
Max size: 100.
Title of item.
user_rating
type: number
Optional.
The average rating purchasers have provided for this product. Range between 1.0 and 5.0. One decimal place allowed. This should be used in conjunction with rating_count.
Example: 4.5
vendor_id
type: string
Optional.
For marketplaces: the ID of the vendor/seller that sells the item.
video
type: array< object >
Optional.
URLs and tags for videos to be used in your ads or in shops. Supports up to 30,000 videos on the catalog level. Tags are optional and, if used, should describe what is in the video.
The maximum video file size is 200 MB. Supported formats include .3g2, .3gp, .3gpp, .asf, .avi, .dat, .divx, .dv, .f4v, .flv, .gif, .m2ts, .m4v, .mkv, .mod, .mov, .mp4, .mpe, .mpeg, .mpeg4, .mpg, .mts, .nsv, .ogm, .ogv, .qt, .tod, .ts, .vob and .wmv
Type of application. Used to recommend your product to the right people. Supported values:
Games
Productivity
Social
Entertainment
Education
Utilities
Lifestyle
Health & Fitness
Business
Other
app_subcategory
type: string
Optional.
Character limit: 200.
Subcategory of the application, such as arcade game. Used to recommend your product to the right people.
applink
type: object< string >
Optional.
Links to mobile apps. A JSON object with the following keys:
ios_url
ios_app_store_id
ios_app_name
android_url
android_package
android_class
android_app_name
availability
type: string
Required.
Availability status: in stock, out of stock, available for order, discontinued.
brand
type: string
Optional.
Character limit: 100.
The name of the publisher of the product.
condition
type: string
Required.
Product condition: new, refurbished, or used.
content_rating
type: string
Optional.
Official rating of the product. Can be shown in ads. Required for restricted audiences in our Advertising policies.
Example: E for Everyone
custom_label_0
custom_label_1
custom_label_2
custom_label_3
custom_label_4
type: string
Optional.
Character limit: 100.
Any relevant information you want to add to your ad creative such as in the headline.
custom_number_0
custom_number_1
custom_number_2
custom_number_3
custom_number_4
type: integer
Optional.
Any number you want to filter products by when you create product sets. Use whole numbers between 0 and 4294967295. Decimals and commas are not supported.
description
type: string
Required.
Character limit: 9999.
A short and relevant description of the product. Shown in ads. Use plain text and don’t enter text in all capital letters.
developer
type: string
Optional.
Character limit: 100.
The name of the developer of the product.
fb_product_category
type: string
Optional.
The Facebook product category for the product. Enter a supported category from the latest downloadable list available on our Business Help Center.
genres
type: string
Optional.
Character limit: 200.
The genre or style of the game or app, such as action or puzzle. Use commas to separate multiple items.
Example: Action,RPG,Multiplayer
google_product_category
type: string
Optional.
The Google product category for the product. Enter a supported category from the latest downloadable list available on our Business Help Center.
id
type: string
Required.
Character limit: 100.
A unique content ID for the item. Each content ID must appear only once in your catalog. To run Advantage+ catalog ads, this ID must exactly match the content ID for the same item in your Meta Pixel code.
image_link
type: string
Required.
The URL for the main image of your product. Shown in ads. Must be in a supported format (JPG/PNG) and at least 500 x 500 pixels.
link
type: string
Required.
The link to the specific product page on your business’s website. Links must begin with http:// or https://.
operating_system
type: string
Optional.
Character limit: 100.
The operating system or device on which the game or app can be used. Use commas to separate multiple items. Supported values:
iOS
Android
Windows
macOS
Linux
Chrome OS
Web
Other
Example: iOS,Android
price
type: string
Optional.
The individual price of the app or software. Do not enter a subscription price. Format the price as a number followed by the 3-letter currency code (ISO 4217 standards). Use a period (.) as the decimal point.
Example: 9.99 USD
rating_count
type: integer
Optional.
The number of users who have left ratings on the application. Can be shown in ads.
Example: 100
sale_price
type: string
Optional.
The discounted price if the item is on sale. Same format as price. A sale price is required if you want to use an overlay for discounted prices.
title
type: string
Required.
Character limit: 200.
The name of the product. Shown in ads.
user_rating
type: number
Optional.
The average user rating the application has. Enter a rating between 0.0 to 5.0, using a single decimal place. Can be shown in ads.
Example: 4.5
Sample APP_AND_SOFTWARE payload
{
"id": "app_001",
"title": "Super Puzzle Game",
"description": "A fun and challenging puzzle game for all ages",
"link": "https://example.com/super-puzzle-game",
"image_link": "https://example.com/app-icon.jpg",
"availability": "in stock",
"condition": "new",
"price": "4.99 USD",
"brand": "GameStudio",
"app_category": "Games",
"app_subcategory": "Puzzle",
"content_rating": "E for Everyone",
"developer": "GameStudio Inc.",
"genres": "Puzzle,Casual",
"operating_system": "iOS,Android",
"user_rating": 4.5,
"rating_count": 1200
}
item_type=DESTINATION
↳
Field
Description
applink
type: object< string >
Optional.
Links to mobile apps. A JSON object with string keys and string values. The following keys are supported:
ios_url
ios_app_store_id
ios_app_name
iphone_url
iphone_app_store_id
iphone_app_name
ipad_url
ipad_app_store_id
ipad_app_name
android_url
android_package
android_class
android_app_name
windows_phone_url
windows_phone_app_id
windows_phone_app_name
address
type: object< string >
Required.
Address of the destination. A JSON object with string keys and string values. The following keys are supported.
Required fields:
city
country
region
Optional fields:
city_id - identifier of the city to be used when constructing URLs
URLs and tags for images to be used in your ads or in shops.
A JSON array containing up to 21 records with the following fields:
url: the URL string of the image
tag: a JSON array of strings. Tags are optional and, if used, should describe what is in the image.
latitude
type: string
Required.
Latitude location of the destination.
longitude
type: string
Required.
Longitude location of the destination.
name
type: string
Required.
Name of the destination.
neighborhood
type: array< string >
Optional.
Max number of neigborhoods allowed: 20. One or more neighborhood(s) for the destination.
Example: ["Soho", "Las Vegas Strip"]
price
type: string
Optional.
Lowest average cost and currency for the destination. Format the price as a number followed by the currency code; use ISO 4217 standards. Use “”.”” as the decimal for the price.
price_change
type: string
Optional.
Price change. Can be used for building product sets and in the ad creative:
0 - No price change
-10 - 10% price drop
20 - 20% price increase.
Example: "0"
type
type: array< string >
Required.
Max number of destination types: 20. Type(s) of destination. A destination can have multiple types.
Example: ["resort", "beach"]
url
type: string
Required.
Link to the website where you can book the destination.
video
type: array< object >
Optional.
URLs and tags for videos to be used in your ads or in shops. Supports up to 30,000 videos on the catalog level. Tags are optional and, if used, should describe what is in the video.
The maximum video file size is 200 MB. Supported formats include .3g2, .3gp, .3gpp, .asf, .avi, .dat, .divx, .dv, .f4v, .flv, .gif, .m2ts, .m4v, .mkv, .mod, .mov, .mp4, .mpe, .mpeg, .mpeg4, .mpg, .mts, .nsv, .ogm, .ogv, .qt, .tod, .ts, .vob and .wmv
Destination airport for the flight. Should be written as an IATA code.
Example: SFO.
destination_city
type: string
Optional.
Name of the destination city for the flight.
image
type: array< object >
Required.
Images to be used in the ads. A JSON array containing up to 21 records with the following fields:
url: the URL string of the image
tag: a JSON array of strings. Tags are optional and, if used, should describe what is in the image.
origin_airport
type: string
Required.
Origin airport for the flight. Should be written as an IATA code.
Example: LHR.
price
type: string
Optional.
Cost and currency of the flight. The price is a number followed by the currency code; use ISO 4217 standards. Use “”.”” as the decimal for the price.
url
type: string
Optional.
Link to the website where you can book the flight.
video
type: array< object >
Optional.
URLs and tags for videos to be used in your ads. Supports up to 30,000 videos on the catalog level. Tags are optional and, if used, should describe what is in the video.
The maximum video file size is 200 MB. Supported formats include .3g2, .3gp, .3gpp, .asf, .avi, .dat, .divx, .dv, .f4v, .flv, .gif, .m2ts, .m4v, .mkv, .mod, .mov, .mp4, .mpe, .mpeg, .mpeg4, .mpg, .mts, .nsv, .ogm, .ogv, .qt, .tod, .ts, .vob and .wmv
Current availability for the home listing. Supported values are: for_sale, for_rent, sale_pending, recently_sold, off_market, available_soon. For commerce, the only supported value is for_rent.
available_dates_price_config
type: array< object >
Optional.
List of dates and prices that a listing is available. When you provide values, Facebook can recommend listings based on their available dates and dynamically show the associated price in your ad.
Type of property listing. Supported values for Advantage+ catalog ads: for_rent_by_agent, for_rent_by_owner, for_sale_by_agent, for_sale_by_owner, foreclosed, new_construction, new_listing. Supported values for commerce: for_rent_by_agent, for_rent_by_owner.
name
type: string
Required.
Name of the home listing.
neighborhood
type: array< string >
Optional.
Neighborhood for the home listing. Max number neighborhoods allowed: 20.
num_rooms
type: integer
Optional.
Total number of rooms in the property.
num_baths
type: integer
Optional.
Total number of bathrooms. For commerce, must be 1 at minimum.
num_beds
type: integer
Optional.
Total number of bedrooms. Can be 0 for Studios.
num_units
type: integer
Optional.
Number of units available. Use only for apartments or condos available for rent/lease.
price
type: string
Required.
Cost and currency for the home listing. The price is a number followed by the currency code; use ISO 4217 standards. Use “”.”” as the decimal for the price.
Link to the website where you can view the listing.
year_built
type: string
Optional.
Year the property was built, using the YYYY format, 4 digit year.
area_size
type: integer
Not applicable for Advantage+ catalog ads. Required for commerce.
Area or space of the floor plan’s listing.
area_unit
type: string
Not applicable for Advantage+ catalog ads. Required for commerce.
The units (square feet or square meters) of the floor area’s value. Supported values: sq_ft, sq_m.
ac_type
type: string
Not applicable for Advantage+ catalog ads. Optional for commerce.
Type of air conditioning. Supported values: central, other, none.
furnish_type
type: string
Not applicable for Advantage+ catalog ads. Optional for commerce.
Type of heating installed in the property. Supported values: central, gas, electric, radiator, other, none.
laundry_type
type: string
Not applicable for Advantage+ catalog ads. Optional for commerce.
Type of laundry available. Supported values: in_unit, in_building, other, none.
parking_type
type: string
Not applicable for Advantage+ catalog ads. Optional for commerce.
Type of parking available on property. Supported values: garage, street, off-street, other, none.
partner_verification
type: string
Not applicable for Advantage+ catalog ads. Optional for commerce.
Whether the partner company has verified the listing. Supported values: verified, none.
pet_policy
type: string
Not applicable for Advantage+ catalog ads. Optional for commerce.
Indicates the pets allowed on the property: cat, dog, all, none.
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
This field was previously called visibility. While we still support the old field name, we recommend that you use the new name.
video
type: array< object >
Optional.
URLs and tags for videos to be used in your ads or in shops. Supports up to 30,000 videos on the catalog level. Tags are optional and, if used, should describe what is in the video.
The maximum video file size is 200 MB. Supported formats include .3g2, .3gp, .3gpp, .asf, .avi, .dat, .divx, .dv, .f4v, .flv, .gif, .m2ts, .m4v, .mkv, .mod, .mov, .mp4, .mpe, .mpeg, .mpeg4, .mpg, .mts, .nsv, .ogm, .ogv, .qt, .tod, .ts, .vob and .wmv
Deep link straight to the hotel details page in your mobile app. See supported fields here.
base_price
type: string
Required.
Base price of the hotel room per night. Add the currency type to the price. Format price as the cost, followed by the ISO currency code, with a space between cost and currency.
Example: 100 USD
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.
Examples: Resort, Day Room
number_of_rooms
type: integer
Optional.
Total number of rooms/units in this hotel listing.
Example: 150
brand
type: integer
Optional.
Brand of the hotel chain.
custom_label_0
custom_label_1
custom_label_2
custom_label_3
custom_label_4
type: string
Optional.
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 rooms into a set. This field supports any text value, including numbers.
Example: Summer Sale
custom_number_0
custom_number_1
custom_number_2
custom_number_3
custom_number_4
type: integer
Optional.
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
internal_label
type: array< string >
Add internal labels to help filter items when you create product sets. For example, you could add a “summer” label to all items that are part of a summer promotion and then filter those items into a set. Labels are only visible to you.
Character limit: Up to 5,000 labels per product and 110 characters per label.
Note: If you’re currently using custom labels (custom_label_0 to custom_label_4) for filtering product sets, switching to internal labels (internal_label) instead is recommended. Unlike custom labels, you can add or update internal labels as often as needed without sending items through policy review each time, which can impact ad delivery.
This field was previously called product_tags. While we still support the old field name, we recommend that you use the new name.
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
image
type: array< object >
Required.
A JSON array containing up to 21 records with the following fields:
url: the URL string of the image
tag: a JSON array of strings. Tags are optional and, if used, should describe what is in the image.
URLs and tags for videos to be used in your ads or in shops. Supports up to 30,000 videos on the catalog level. Tags are optional and, if used, should describe what is in the video.
The maximum video file size is 200 MB. Supported formats include .3g2, .3gp, .3gpp, .asf, .avi, .dat, .divx, .dv, .f4v, .flv, .gif, .m2ts, .m4v, .mkv, .mod, .mov, .mp4, .mpe, .mpeg, .mpeg4, .mpg, .mts, .nsv, .ogm, .ogv, .qt, .tod, .ts, .vob and .wmv
Loyalty program you use to gain points for staying at the hotel.
margin_level
type: string
Optional.
Indicator of the hotel’s profitability; value from 1 to 10.
Example: 7
name
type: string
Required.
Name of the hotel.
neighborhood
type: array< string >
Optional.
One or more neighborhood(s) for the hotel. Max number of neigborhoods allowed: 20.
Example: ["Soho", "Las Vegas Strip"]
phone
type: string
Optional.
Phone number with country code.
status
type: string
Optional.
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
This field was previously called visibility. While we still support the old field name, we recommend that you use the new name.
Sale price
type: string
Optional.
Note: this field has a space character in its name
Sale price per night in the hotel. Use this to advertise discounts off the regular hotel price. Required: Add the currency type to the price. Format price as the cost, followed by the ISO currency code, with a space between cost and currency.
Example: 99 USD
Star rating
type: Integer
Optional.
Hotel star rating. Number should be between 1 and 5.
Example: 3
uri
type: string
Required.
Link to the website where you book the hotel room.
URLs and tags for videos to be used in your ads or in shops. Supports up to 30,000 videos on the catalog level. Tags are optional and, if used, should describe what is in the video.
The maximum video file size is 200 MB. Supported formats include .3g2, .3gp, .3gpp, .asf, .avi, .dat, .divx, .dv, .f4v, .flv, .gif, .m2ts, .m4v, .mkv, .mod, .mov, .mp4, .mpe, .mpeg, .mpeg4, .mpg, .mts, .nsv, .ogm, .ogv, .qt, .tod, .ts, .vob and .wmv
Indicator of the hotel’s profitability; value from 1 to 10.
name
type: string
Required.
Max size: 100.
Name of the room.
url
type: string
Required.
Link to advertiser’s site where someone can book the stay.
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: published, archived. Items are active by default. Learn more about archiving items.
Example: published
This field was previously called visibility. While we still support the old field name, we recommend that you use the new name.
An actor in a production such as a movie or TV show. Use commas to separate multiple names.
applink
type: object< string >
Optional.
Links to mobile apps. A JSON object with the following keys:
ios_url
ios_app_store_id
ios_app_name
android_url
android_package
android_class
android_app_name
availability
type: string
Required.
Availability status: in stock, out of stock, available for order, discontinued.
award
type: string
Optional.
Character limit: 200.
Any notable awards or nominations. Use commas to separate multiple items.
brand
type: string
Optional.
Character limit: 100.
The streaming service or platform where this product is available.
condition
type: string
Required.
Product condition: new, refurbished, or used.
content_rating
type: string
Optional.
Official rating of the media title. Can be shown in ads. Required for restricted audiences in our Advertising policies.
Example: PG-13
custom_label_0
custom_label_1
custom_label_2
custom_label_3
custom_label_4
type: string
Optional.
Character limit: 100.
Any relevant information you want to add to your ad creative such as in the headline.
custom_number_0
custom_number_1
custom_number_2
custom_number_3
custom_number_4
type: integer
Optional.
Any number you want to filter products by when you create product sets. Use whole numbers between 0 and 4294967295. Decimals and commas are not supported.
description
type: string
Required.
Character limit: 9999.
A short and relevant description of the product such as a plot summary for a movie. Shown in ads. Use plain text and don’t enter text in all capital letters.
director
type: string
Optional.
Character limit: 200.
A director of a production like a movie or radio show. Use commas to separate multiple names.
Example: John Doe,Jane Doe
duration
type: string
Optional.
The duration of the product. Use the format HH-MM-SS (ISO 8601 standard).
Example: 02-34-15
featuring
type: string
Optional.
Character limit: 200.
The names of key individuals involved in the production such as artists or producers. Use commas to separate multiple names.
genres
type: string
Optional.
Character limit: 200.
The media genre such as action or comedy. Use commas to separate multiple genres.
Example: Action,Fantasy
global_unique_identifier
type: string
Optional.
Any identifier that represents a work of film or television. For example: EIDR (Entertainment Identifier Registry).
Example: 10.5240/B752-5B47-DBBE-E5D4-5A3F-N
id
type: string
Required.
Character limit: 100.
A unique content ID for the item. Each content ID must appear only once in your catalog. To run Advantage+ catalog ads, this ID must exactly match the content ID for the same item in your Meta Pixel code.
image_link
type: string
Required.
The URL for the main image of your product. Shown in ads. Must be in a supported format (JPG/PNG) and at least 500 x 500 pixels.
link
type: string
Required.
The link to the specific product page on your business’s website. Links must begin with http:// or https://.
media_category
type: string
Optional.
The content category of the product. Used to recommend your products to the right audiences. Supported values:
Movie
Music
TV Show
Other
price
type: string
Optional.
The individual price of the media. Do not enter a subscription price. Format the price as a number followed by the 3-letter currency code (ISO 4217 standards). Use a period (.) as the decimal point.
Example: 9.99 USD
production_company
type: string
Optional.
Character limit: 200.
The production company or studio that created the product. Use commas to separate multiple items.
release_date
type: string
Optional.
The release date of the product. Use the format YYYY-MM-DD.
Example: 2025-02-16
sale_price
type: string
Optional.
The discounted price if the item is on sale. Same format as price. A sale price is required if you want to use an overlay for discounted prices.
title
type: string
Required.
Character limit: 200.
The title of the product. Shown in ads.
Sample MEDIA_TITLE payload
{
"id": "movie_001",
"title": "The Great Adventure",
"description": "An epic journey across the world",
"link": "https://example.com/the-great-adventure",
"image_link": "https://example.com/poster.jpg",
"availability": "in stock",
"condition": "new",
"price": "14.99 USD",
"brand": "StreamFlix",
"media_category": "Movie",
"genres": "Action,Adventure",
"content_rating": "PG-13",
"release_date": "2025-06-15",
"director": "Jane Smith",
"actor": "John Doe,Alice Johnson",
"duration": "02-15-00",
"custom_label_0": "Summer Release"
}
Optional unless you want local pricing to populate in the ads. If the price is not available for a product in the local feed, then that product’s ad will fetch its price from the online feed.
quantity
type: number
Optional.
Quantity will be default to 0 if it’s not provided, but items can still be delivered if availability is in stock.
availability
Type: string
Optional.
If not set, the item is assumed to be available (in stock) for the given store. If the item is not available in the given store, it doesn’t have to be provided in the local feed, but uploading it as “out of stock” availability may simplify “update-only” feed uploads.
Identifies availability status:
in stock
out of stock
sale_price
Type: integer
Optional.
Local sale price.
sale_price_effective_date
Type: string
Optional.
Date range over which the sale is valid. Format is 2020-02-28T12:00-0800/2020-05-08T12:00-0800, where / is the delimiter. You cannot give only a start or end date. You must give both. If you leave it blank, then the sale date will be permanent until the sale_price is changed to null.
pickup_timeline
Type: integer
Optional.
The timeline for when people can pick up the item. Can be “same day” or “next day”.
pickup_method
Type: string
Optional.
The method by which people can pick up the item. Can be “buy,” “reserve” or “not supported”.
↳
Refer to Automotive Model Ads documentation for the list of supported fields. Please note that while in CSV and TSV feed files the ‘image’ field is spread across multiple columns (such as ‘image[0].url’, ‘image[0].tag’, ‘image[1].url’ etc.). In the /items_batch API endpoint there is no need to do so, instead the ‘image’ field is represented as a single JSON object (see example below).