Product Catalog

Updated: Mar 5, 2026

Copy for LLM

Represents a catalog for your business you can use to deliver ads with dynamic ads.

Example — View all product catalogs associated to your business

curl -G \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/owned_product_catalogs"

You can associate pixels and apps with a product catalog and then display products in ads based on signals from pixels or apps.

Example — Make an HTTP POST

curl \
  -F 'external_event_sources=[<PIXEL_ID>,<APP_ID>]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<PRODUCT_CATALOG_ID>/external_event_sources

Permissions

You need the appropriate Marketing API Access Level and must accept the Terms of Service⁠ by creating your first catalog through Business Manager⁠.

Reading

Product catalogs contain a list of items like products, hotels or flights, and the information needed to display them in dynamic ads

Parameters

Parameter	Description
`segment_use_cases` array<enum {AFFILIATE_SELLER_STOREFRONT, AFFILIATE_TAGGED_ONLY_DEPRECATED, COLLAB_ADS, COLLAB_ADS_FOR_MARKETPLACE_PARTNER, COLLAB_ADS_SEGMENT_WITHOUT_SEGMENT_SYNCING, DIGITAL_CIRCULARS, FB_LIVE_SHOPPING, IG_SHOPPING, IG_SHOPPING_SUGGESTED_PRODUCTS, MARKETPLACE_SHOPS, TEST}>	segment_use_cases

Fields

Field	Description
`id` numeric string	ID of a catalog default
`business` Business	Business that owns a catalog
`da_display_settings` ProductCatalogImageSettings	Image display settings such as background cropping and padding of items in the catalog for different Dynamic Ad formats
`default_image_url` string	The URL for the default image, which is used for products without images, or when the product image is temporarily unavailable. If a product image matches the default image, this should be treated as if the image was not loaded
`fallback_image_url` list<string>	The URL for the fallback image. This is used as the image for auto-generated dynamic items
`feed_count` int32	The total number of feeds used by a catalog
`is_catalog_segment` bool	Verify that you will create ads based on a catalog or catalog segment before you try to create Dynamic Ads. Call this field and determine value otherwise you may get and error when you try to create Dynamic Ads from catalog segments.
`is_local_catalog` bool	is_local_catalog
`name` string	The name of a catalog given by the creator default
`product_count` int32	The total number of products in a catalog
`vertical` enum	The type of catalog (for example: hotels, commerce, etc)

Edges

Edge	Description
`agencies` Edge<Business>	Agencies that have access to a catalog
`assigned_users` Edge<AssignedUser>	Users assigned to this catalog
`automotive_models` Edge<AutomotiveModel>	Automotive models that a catalog contains
`categories` Edge<ProductCatalogCategory>	Categories within the catalog for a given categorization criteria
`check_batch_request_status` Edge<CheckBatchRequestStatus>	Checks the status of a batch request
`collaborative_ads_share_settings` Edge<CollaborativeAdsShareSettings>	All the collaborative ads share settings for a catalog segment
`data_sources` Edge<ProductCatalogDataSource>	data_sources updating catalog including feeds, session containers etc
`destinations` Edge<Destination>	Destinations that a catalog contains
`diagnostics` Edge<ProductCatalogDiagnosticGroup>	diagnostics
`event_stats` Edge<ProductEventStat>	Aggregated statistics on the matched and unmatchd events received from the pixels and apps associated to the catalog, broken down by DA event, source and device_type
`external_event_sources` Edge<ExternalEventSource>	External event sources (including pixels) for catalog events like ViewContent
`flights` Edge<Flight>	Flights that a catalog contains
`home_listings` Edge<HomeListing>	Home listings that a catalog contains
`hotel_rooms_batch` Edge<ProductCatalogHotelRoomsBatch>	Batch operations with hotel rooms
`hotels` Edge<Hotel>	Hotels that a catalog contains
`pricing_variables_batch` Edge<ProductCatalogPricingVariablesBatch>	Batch operations with hotel room prices
`product_groups` Edge<ProductGroup>	Product groups that a catalog contains
`product_sets` Edge<ProductSet>	Product sets belonging to a catalog
`product_sets_batch` Edge<ProductCatalogProductSetsBatch>	Batch operations with product sets
`products` Edge<ProductItem>	Products that a catalog contains
`vehicle_offers` Edge<VehicleOffer>	Vehicle offers that a catalog contains
`vehicles` Edge<Vehicle>	Vehicles that a catalog contains

Error Codes

Error Code	Description
100	Invalid parameter
368	The action attempted has been deemed abusive or is otherwise disallowed
190	Invalid OAuth 2.0 Access Token
200	Permissions error
2500	Error parsing graph query

Creating

Examples

curl \
  -F 'name=Catalog' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/product_catalogs

/{product_catalog_id}/assigned_users

You can make a POST request to assigned_users edge from the following paths:

/{product_catalog_id}/assigned_users

When posting to this edge, a ProductCatalog will be created.

Parameters

Parameter	Description
`tasks` array<enum {MANAGE, ADVERTISE, MANAGE_AR, AA_ANALYZE}>	Catalog permission tasks to assign this user required
`user` UID	Business user id or system user id required

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct  {
success: bool,
}

Error Codes

Error Code	Description
100	Invalid parameter
200	Permissions error
415	Two factor authentication required. User have to enter a code from SMS or TOTP code generator to pass 2fac. This could happen when accessing a 2fac-protected asset like a page that is owned by a 2fac-protected business manager.

/{product_catalog_id}/vehicles

You can make a POST request to vehicles edge from the following paths:

/{product_catalog_id}/vehicles

When posting to this edge, a ProductCatalog will be created.

Parameters

Parameter	Description
`address` JSON object	address required `city` string Default value: `""` city `city_id` string city_id `country` string Default value: `""` country `latitude` float latitude `longitude` float longitude `neighborhoods` array<string> neighborhoods `postal_code` string Default value: `""` postal_code `region` string Default value: `""` region `street_address` string Default value: `""` street_address Show child parameters
`applinks` Object	applinks `web` `android` `ios` `ipad` `iphone` `windows_phone` Show child parameters
`availability` enum {AVAILABLE, NOT_AVAILABLE, PENDING, UNKNOWN}	availability
`body_style` enum {CONVERTIBLE, COUPE, CROSSOVER, ESTATE, GRANDTOURER, HATCHBACK, MINIBUS, MINIVAN, MPV, PICKUP, ROADSTER, SALOON, SEDAN, SMALL_CAR, SPORTSCAR, SUPERCAR, SUPERMINI, SUV, TRUCK, VAN, WAGON, OTHER, NONE}	body_style required
`condition` enum {EXCELLENT, VERY_GOOD, GOOD, FAIR, POOR, OTHER, NONE}	condition
`currency` ISO 4217 Currency Code	currency required
`date_first_on_lot` string	date_first_on_lot
`dealer_id` string	dealer_id
`dealer_name` string	dealer_name
`dealer_phone` string	dealer_phone
`description` string	description required
`drivetrain` enum {TWO_WD, FOUR_WD, AWD, FWD, RWD, OTHER, NONE}	drivetrain
`exterior_color` string	exterior_color required
`fb_page_id` string	fb_page_id
`fuel_type` enum {DIESEL, ELECTRIC, GASOLINE, FLEX, HYBRID, OTHER, PETROL, PLUGIN_HYBRID, NONE}	fuel_type
`images` list<Object>	images required `image_url` URL required `tags` list<string> Show child parameters
`interior_color` string	interior_color
`make` string	make required
`mileage` JSON object	mileage required `unit` enum {KILOMETERS, MILES} Default value: `"MILES"` unit `value` int64 Default value: `0` value Show child parameters
`model` string	model required
`price` int64	price required
`state_of_vehicle` enum {NEW, USED, CPO}	state_of_vehicle required
`title` string	title required
`transmission` enum {AUTOMATIC, MANUAL, OTHER, NONE}	transmission
`trim` string	trim
`url` URI	url required
`vehicle_id` string	vehicle_id required
`vehicle_type` enum {BOAT, CAR_TRUCK, COMMERCIAL, MOTORCYCLE, OTHER, POWERSPORT, RV_CAMPER, TRAILER}	vehicle_type
`vin` string	vin required
`year` int64	year required

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct  {
id: numeric string,
}

Error Codes

Error Code	Description
10800	Duplicate retailer_id when attempting to create a store collection
100	Invalid parameter
200	Permissions error

/{business_id}/owned_product_catalogs

You can make a POST request to owned_product_catalogs edge from the following paths:

/{business_id}/owned_product_catalogs

When posting to this edge, a ProductCatalog will be created.

Parameters

Parameter	Description
`additional_vertical_option` enum {LOCAL_DA_CATALOG, LOCAL_PRODUCTS}	Additional catalog configurations that does not introduce either new verticals or subverticals
`business_metadata` JSON object	business_metadata `page_id` numeric string page_id required `external_business_id` string external_business_id Show child parameters
`catalog_segment_filter` A JSON-encoded rule	Provide filter for catalog to create a catalog segment.
`da_display_settings` Object	Dynamic Ads display settings. `carousel_ad` Object required `transformation_type` enum{background_cropping_and_padding, background_padding, none} required Show child parameters `single_ad` Object required `transformation_type` enum{background_cropping_and_padding, background_padding, none} required Show child parameters Show child parameters
`destination_catalog_settings` JSON object	Destination catalog settings. `generate_items_from_pages` boolean Default value: `false` Show child parameters
`flight_catalog_settings` JSON object	Flight catalog settings. `generate_items_from_events` boolean Default value: `false` Show child parameters
`name` UTF-8 encoded string	Name of the catalog. required
`parent_catalog_id` numeric string or integer	Parent catalog ID.
`partner_integration` JSON object	Partner integration settings `external_access_token` string External access token `external_merchant_id` string External merchant identifier Show child parameters
`store_catalog_settings` JSON object	Store catalog settings. `page_id` numeric string page_id required Show child parameters
`vertical` enum {adoptable_pets, apps_and_software, articles_and_publications, commerce, destinations, flights, generic, home_listings, hotels, local_service_businesses, media_titles, offer_items, services, offline_commerce, transactable_items, vehicles}	Default value: `commerce` The catalog's industry or vertical, such as `commerce`.

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct  {
id: numeric string,
}

Error Codes

Error Code	Description
100	Invalid parameter
190	Invalid OAuth 2.0 Access Token
804	Specified object already exists
102	Session key invalid or no longer valid
200	Permissions error
2310019	The business of this catalog is not onboarded to Collaborative Ads

Updating

/{product_catalog_id}

You can update a ProductCatalog by making a POST request to /{product_catalog_id}.

Parameters

Parameter	Description
`additional_vertical_option` enum {LOCAL_DA_CATALOG, LOCAL_PRODUCTS}	Additional catalog configurations that does not introduce either new verticals or subverticals
`da_display_settings` Object	The display settings object when used will determine which image transformations (like cropping or padding) will be applied for the item in the specified dynamic ad format. `carousel_ad` Object required `transformation_type` enum{background_cropping_and_padding, background_padding, none} required Show child parameters `single_ad` Object required `transformation_type` enum{background_cropping_and_padding, background_padding, none} required Show child parameters Show child parameters
`default_image_url` URI	The URL for the default image, which is used for products without images or for the cases when the product image is temproarily unavailable. If a product image matches the default image, this should be treated as if the image was not loaded.
`destination_catalog_settings` JSON object	Catalog setting for destination catalogs. `generate_items_from_pages` boolean Default value: `false` Show child parameters
`fallback_image_url` URI	The URL for the fallback image. This is used as the image for the auto-generated dynamic items.
`flight_catalog_settings` JSON object	Catalog setting for flight catalogs. `generate_items_from_events` boolean Default value: `false` Show child parameters
`name` string	Name of the Product Catalog
`partner_integration` JSON object	Partner integration settings `external_access_token` string External access token `external_merchant_id` string External merchant identifier Show child parameters
`store_catalog_settings` JSON object	Catalog settings for store catalogs; the page with the location structure for all the stores within this settings will be used to validate the store number for feed uploading `page_id` numeric string page_id required Show child parameters

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct  {
success: bool,
}

Error Codes

Error Code	Description
200	Permissions error
100	Invalid parameter

/{product_catalog_id}/marketplace_partner_signals

You can update a ProductCatalog by making a POST request to /{product_catalog_id}/marketplace_partner_signals.

Parameters

Parameter	Description
`conversion_type` enum {ATTRIBUTED, IN_SESSION}	conversion_type Identifier on whether the specified event happened within the original session of the user landing on the partner's page (IN_SESSION) or within the attribution window after the initial session (ATTRIBUTED)
`event_id` string	event_id Unique identifier for conversion events. If there are multiple conversion events tied to a single `mp_clid`, this field will be used to differentiate between those events
`event_name` enum {PURCHASE, ADD_TO_CART, VIEW_ITEM, OFFER_SUBMITTED, PURCHASE_VIA_OFFER, TEST}	event_name `TEST` events can be used to send test data to confirm API functionality that Marketplace will ignore required
`event_source_url` string	event_source_url
`event_time` datetime/timestamp	event_time required
`offer_data` JSON object	offer_data `original_price` float original_price required `offer_price` float offer_price required `currency` string currency required Show child parameters
`order_data` JSON object	order_data `order_details` array<JSON object> Default value: `[]` order_details `item_price` float item_price required `item_quantity` int64 item_quantity required `item_id` string item_id required Show child parameters `currency` string currency required `order_total` float order_total required Show child parameters
`user_data` JSON object	user_data required `mp_clid` string mp_clid required Show child parameters

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct  {
success: bool,
validation_status:  List  [ Struct  {
errors:  List  [ Struct  {
message: string,
}],
warnings:  List  [ Struct  {
message: string,
}],
}],
}

Error Codes

Error Code	Description
100	Invalid parameter

Deleting

Examples

You can delete a product catalog with the following API. You cannot remove a product catalog from a Business Manager, or transfer a catalog from one Business Manager to another.

curl -X DELETE \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>

To do this in a batch call, specify the parameter in the query string for the URL:

curl \
  -F 'batch=[{
  "method":"DELETE",
  "relative_url":"<PRODUCT_CATALOG_ID>"
}]' \
 -F 'access_token=<TOKEN>' \
  https://graph.facebook.com

To remove the association between the catalog and a pixel or app, make an HTTP DELETE:

curl -X DELETE \
  -F 'external_event_sources=[<APP_ID>,<PIXEL_ID>]' \
  -F 'access_token=<TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/external_event_sources

To see all pixel and apps associated with a product catalog, make an HTTP GET:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/external_event_sources

/{product_catalog_id}

You can delete a ProductCatalog by making a DELETE request to /{product_catalog_id}.

Parameters

Parameter	Description
`allow_delete_catalog_with_live_product_set` boolean	Default value: `false` If the catalog has live product sets, the deletion will be blocked by default. Set this parameter to true to enforce the deletion even if it has live product sets

Return Type

Struct  {
success: bool,
}

Error Codes

Error Code	Description
3970	You must be assigned as an admin of this product catalog before you can delete it.
801	Invalid operation
100	Invalid parameter

/{product_catalog_id}/assigned_users

You can dissociate a ProductCatalog from a ProductCatalog by making a DELETE request to /{product_catalog_id}/assigned_users.

Parameters

Parameter	Description
`user` UID	Business user id or system user id required

Return Type

Struct  {
success: bool,
}

Error Codes

Error Code	Description
100	Invalid parameter