Meta / Facebook Developer Docs Mirror

Appearance

Mirrored from https://developers.facebook.com/documentation/ads-commerce/catalog/get-started/integrate-via-meta-sdk

Catalog: Supported Products and Services ​

Updated: May 29, 2026

We are introducing new API endpoints designed to enable the adoption of new industries (business verticals). This expansion enables you to manage items across a broader range of categories, such as Media Titles, while maintaining a familiar integration experience.

Overview ​

The Catalog APIs have long supported non-commerce verticals such as Hotels and Flights, offering the same level of API support as for commerce items. To further expand catalog coverage, the following verticals are now available:

  • Media Titles — movies, TV shows, music, and other streaming content
  • Apps and Software — mobile apps, desktop software, and games
  • Articles and Publications — ebooks, audiobooks, magazines, newspapers, and other written content
  • Professional Services — local and online services such as consulting, coaching, repair, and wellness
  • Activities — concerts, sporting events, guided tours, and other bookable activities

If you have previously integrated with the Catalog API for other verticals, the experience is very similar. Existing endpoints have been extended with new values for item types and verticals to support these categories.

Key Changes ​

These are the most important changes to know about when starting your integration:

  • New vertical options when creating Catalogs. When creating catalogs through the API, new vertical values are available for these verticals, such as media_titles, apps_and_software, articles_and_publications, services, and activities. Use these values to create catalogs for the corresponding vertical.
  • New feed type options when creating Feeds. When creating feeds through the API, new feed type values are available, such as MEDIA_TITLE, APP_AND_SOFTWARE, ARTICLE_AND_PUBLICATION, SERVICE, and ACTIVITY. Use these values to create feeds for the corresponding vertical.
  • New item type options for Batch API. When managing items through the Batch API, new item_type values are available, such as MEDIA_TITLE, APP_AND_SOFTWARE, ARTICLE_AND_PUBLICATION, SERVICE, and ACTIVITY. Structure your data object following the fields supported for your chosen item type.
  • New attributes for Product Set filters. Some vertical-specific attributes can be used to create product sets. For example, for media titles, you can filter by award, director, and more. For professional services, you can filter by service_category, has_certification, and more. For activities, you can filter by activity_category, activity_date, and more. For a complete list of filterable fields, see the guides below for the vertical you are integrating with.

In addition to these changes on existing endpoints, new edges are available for each vertical to enable reading items from a Catalog, Product Set, and Feed. For example, see reading your media titles.

Create a Catalog ​

A catalog is a container for your 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 catalog, set vertical as required. For example, to create a media titles catalog, set vertical to media_titles:

curl -X POST \
  -F 'name="Test catalog"' \
  -F 'vertical="media_titles"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/{business-id}/owned_product_catalogs

Upload Items Using the API ​

Once you have created the catalog, upload your items. See the following reference documents for all available upload methods:

Use the Catalog API to create a feed object for every feed you want to upload. Both scheduled and direct uploads are supported.

For scheduled uploads, specify a schedule when you create the feed. For direct uploads, omit the schedule.

Scheduled feed example:

curl -X POST \
  -F 'name="Test feed"' \
  -F 'schedule={
       "interval": "DAILY",
       "url": "http://www.example.com/sample_feed.csv",
       "hour": "22"
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/product_feeds

The response returns the feed ID:

{
  "id": "<PRODUCT_FEED_ID>"
}

Direct upload example:

Once you have created the feed (with or without a schedule), you can perform a one-time upload using the PRODUCT_FEED_ID:

curl \
  -F "url=http://www.example.com/sample_feed.csv" \
  -F "access_token=<ACCESS_TOKEN>" \
  https://graph.facebook.com/<API_VERSION>/<PRODUCT_FEED_ID>/uploads

Supported feed formats ​

Below are sample CSV files for each business vertical:

Media Titles CSV sample Apps and Software CSV sample Articles and Publications CSV sample Professional Services CSV sample

Note:

  • The first row in the CSV file must list the field names in the order values will be provided. Subsequent rows supply the corresponding values for each item.
  • Fields containing whitespace or commas should be enclosed in double quotes.
  • Nested or multi-value fields such as image can be represented using JSON-encoded values or by a set of flattened plain-text columns labeled using JSON-path syntax, such as image[0].url, image[0].tag[0], image[0].tag[1]. Both conventions can be used interchangeably in the same file.

Filter Items Into Sets ​

A set is a subset of the items in your catalog. Product sets are defined by filters applied to the catalog. You can use each business vertical's edge to list items that belong to a specific product set. See the following links for full reference documentation for each edge:

Filter Media Titles Into Sets ​

You can create a set containing only movies or only items from a specific director. You can also create a set without any filters, in which case it will contain all items in your catalog.

The following fields are available as product set filters:

FieldDescription
awardsFilter by notable awards or nominations.
brandFilter by streaming service or platform name.
castFilter by actors in the production.
currencyFilter by ISO 4217 currency code.
custom_label_0 through custom_label_4Filter by custom label values.
descriptionFilter by item description text.
directorFilter by director of the production.
featuringFilter by featured artists or key individuals in the production.
genreFilter by media genre such as action, comedy, or drama.
media_categoryFilter by content category: Movie, Music, TV Show, or Other.
nameFilter by the title of the media item.
price_amountFilter by the numeric price amount.
production_companyFilter by production company or studio.
release_dateFilter by release date (YYYY-MM-DD format).
release_date_timeFilter by release date and time.
retailer_idFilter by the retailer-provided unique identifier.
tagsFilter by product organization tags.

For the full list of filter operators, see Product Set.

Read Your Media Titles ​

To read media titles in your catalog, use any of the following endpoints:

Filter Apps and Software Into Sets ​

You can create a set containing only games or only items from a specific developer. You can also create a set without any filters, in which case it contains all items in your catalog.

The following fields are available as product set filters:

FieldDescription
app_categoryFilter by application type: Games, Productivity, Social, Entertainment, Education, Utilities, Lifestyle, Health & Fitness, Business, or Other.
app_subcategoryFilter by application subcategory such as arcade game.
brandFilter by publisher name.
content_ratingFilter by official content rating.
currencyFilter by ISO 4217 currency code.
custom_label_0 through custom_label_4Filter by custom label values.
descriptionFilter by item description text.
developerFilter by the developer of the app or software.
genreFilter by genre or style such as action or puzzle.
nameFilter by the name of the app or software.
price_amountFilter by the numeric price amount.
retailer_idFilter by the retailer-provided unique identifier.
tagsFilter by product organization tags.

For the full list of filter operators, see Product Set.

Read Your Apps and Software Items ​

To read apps and software items in your catalog, use any of the following endpoints:

Filter Articles and Publications Into Sets ​

You can create a set containing only ebooks or only items from a specific author. You can also create a set without any filters, in which case it contains all items in your catalog.

The following fields are available as product set filters:

FieldDescription
authorFilter by the author(s) of the article or publication.
awardsFilter by notable awards or nominations.
brandFilter by publishing entity or platform name.
content_ratingFilter by official content rating.
currencyFilter by ISO 4217 currency code.
custom_label_0 through custom_label_4Filter by custom label values.
date_publishedFilter by publication date (YYYY-MM-DD format).
descriptionFilter by item description text.
genreFilter by genre such as mystery, biography, or science fiction.
in_languageFilter by content language (ISO language codes).
nameFilter by the title of the article or publication.
price_amountFilter by the numeric price amount.
publication_categoryFilter by publication format: Article, Ebook, Audiobook, Blogpost, Book, Magazine, Newspaper, Report, Whitepaper, Journal, Newsletter, or Other.
retailer_idFilter by the retailer-provided unique identifier.
tagsFilter by product organization tags.

For the full list of filter operators, see Product Set.

Read Your Articles and Publications Items ​

To read articles and publications in your catalog, use any of the following endpoints:

Filter Professional Services Into Sets ​

You can create a set containing only services in a specific category or only certified providers. You can also create a set without any filters, in which case it contains all items in your catalog.

The following fields are available as product set filters:

FieldDescription
awardFilter by notable awards or recognitions.
brandFilter by service provider or business name.
currencyFilter by ISO 4217 currency code.
custom_label_0 through custom_label_4Filter by custom label values.
descriptionFilter by item description text.
has_certificationFilter by professional certifications held.
nameFilter by the name of the service.
price_amountFilter by the numeric price amount.
retailer_idFilter by the retailer-provided unique identifier.
service_categoryFilter by the type of service offered.
tagsFilter by product organization tags.

For the full list of filter operators, see Product Set.

Read Your Professional Services Items ​

To read professional services in your catalog, use any of the following endpoints:

Filter Activities Into Sets ​

You can create a set containing only concerts or only activities from a specific performer. You can also create a set without any filters, in which case it contains all items in your catalog.

The following fields are available as product set filters:

FieldDescription
activity_categoryFilter by activity type, such as concert, sporting event, or guided tour.
activity_sub_categoryFilter by a more specific categorization, such as football or basketball for sporting events.
activity_dateFilter by scheduled date of the activity.
brandFilter by activity provider, organizer, or seller.
currencyFilter by ISO 4217 currency code.
custom_label_0 through custom_label_4Filter by custom label values.
descriptionFilter by item description text.
in_languageFilter by language of the content or performance (ISO language codes).
location_nameFilter by venue or location name.
nameFilter by the title of the activity.
performerFilter by performers at the event, such as a musician or actor.
price_amountFilter by the numeric price amount.
retailer_idFilter by the retailer-provided unique identifier.
tagsFilter by product organization tags.

For the full list of filter operators, see Product Set.

Read Your Activities Items ​

To read activities in your catalog, use any of the following endpoints:

Unofficial mirror for reference/search purposes. All content originates from developers.facebook.com — see the source link at the top of each page. Machine-readable indexes: llms.txt · llms-full.txt · About

Content © Meta Platforms, Inc. · Built by Arjun Aditya