Versione API Graph

Product Catalog

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[0]=<PIXEL_ID>' \ 
  -F 'external_event_sources[1]=<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.

Lettura

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

Parametri

Parametro Descrizione

Parametro	Descrizione
`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

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

Campi

Campo	Descrizione
`id` numeric string	ID of a catalog Standard
`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 Standard
`product_count` int32	The total number of products in a catalog
`vertical` enum	The type of catalog (for example: hotels, commerce, etc)

Segmenti

Segmento	Descrizione
`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

Errore	Descrizione
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
80009	There have been too many calls to this Catalog account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
2500	Error parsing graph query

Creazione

Examples

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

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

/{product_catalog_id}/items_batch

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

Parametri

Parametro	Descrizione
`allow_upsert` boolean	Valore predefinito: `true` Parameters specifying whether non existing items that are being updated should be inserted or should throw the error
`item_sub_type` enum {APPLIANCES, BABY_FEEDING, BABY_TRANSPORT, BEAUTY, BEDDING, CAMERAS, CELL_PHONES_AND_SMART_WATCHES, CLEANING_SUPPLIES, CLOTHING, CLOTHING_ACCESSORIES, COMPUTERS_AND_TABLETS, DIAPERING_AND_POTTY_TRAINING, ELECTRONICS_ACCESSORIES, FURNITURE, HEALTH, HOME_GOODS, JEWELRY, NURSERY, PRINTERS_AND_SCANNERS, PROJECTORS, SHOES_AND_FOOTWEAR, SOFTWARE, TOYS, TVS_AND_MONITORS, VIDEO_GAME_CONSOLES_AND_VIDEO_GAMES, WATCHES}	Valore predefinito: `"EMPTY"` The sub vertical type of items in the request
`item_type` string	The type of items in the request Obbligatorio
`requests` JSON object	Array of JSON objects containing batch requests. Each batch request consists of `method` and `data` fields Obbligatorio

Tipo di ricavo

Questo endopoint supporta read-after-write e leggerà il nodo in cui hai effettuato una richiesta POST.

Struct {

handles: List [

string

validation_status: List [

Struct {

errors: List [

Struct {

message: string,

}

retailer_id: string,

warnings: List [

Struct {

message: string,

}

Error Codes

Errore	Descrizione
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 https://developers.facebook.com/docs/graph-api/overview/rate-limiting#catalog.
100	Invalid parameter
200	Permissions error
190	Invalid OAuth 2.0 Access Token
368	The action attempted has been deemed abusive or is otherwise disallowed

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.

Parametri

Parametro	Descrizione
`additional_vertical_option` enum {LOCAL_DA_CATALOG, LOCAL_PRODUCTS}	Additional catalog configurations that does not introduce either new verticals or subverticals
`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	Obbligatorio
`transformation_type` enum{background_cropping_and_padding, background_padding, none}	Obbligatorio
`single_ad` Object	Obbligatorio
`transformation_type` enum{background_cropping_and_padding, background_padding, none}	Obbligatorio
`destination_catalog_settings` JSON object	Destination catalog settings.
`generate_items_from_pages` boolean	Valore predefinito: `false`
`flight_catalog_settings` JSON object	Flight catalog settings.
`generate_items_from_events` boolean	Valore predefinito: `false`
`name` UTF-8 encoded string	Name of the catalog. Obbligatorio
`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
`store_catalog_settings` JSON object	Store catalog settings.
`page_id` numeric string	page_id Obbligatorio
`vertical` enum {adoptable_pets, commerce, destinations, flights, generic, home_listings, hotels, jobs, local_service_businesses, offer_items, offline_commerce, transactable_items, vehicles}	Valore predefinito: `commerce` The catalog's industry or vertical, such as `commerce`.

Tipo di ricavo

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

Struct {

id: numeric string,

}

Error Codes

Errore	Descrizione
100	Invalid parameter
200	Permissions error
2310068	Cannot create a catalog segment from a non CPAS compliant parent catalog
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.

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.

Parametri

Parametro Descrizione

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

tasks

array<enum {MANAGE, ADVERTISE, MANAGE_AR, AA_ANALYZE}>

Catalog permission tasks to assign this user

Obbligatorio

user

UID

Business user id or system user id

Obbligatorio

Tipo di ricavo

Questo endopoint supporta read-after-write e leggerà il nodo in cui hai effettuato una richiesta POST.

Struct {

success: bool,

}

Error Codes

Errore	Descrizione
100	Invalid parameter
200	Permissions error

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.

Parametri

Parametro	Descrizione
`address` JSON object	address Obbligatorio
`city` string	Valore predefinito: `""` city
`city_id` string	city_id
`country` string	Valore predefinito: `""` country
`latitude` float	latitude
`longitude` float	longitude
`neighborhoods` array<string>	neighborhoods
`postal_code` string	Valore predefinito: `""` postal_code
`region` string	Valore predefinito: `""` region
`street_address` string	Valore predefinito: `""` street_address
`applinks` Object	applinks
`web`
`android`
`ios`
`ipad`
`iphone`
`windows_phone`
`availability` enum {AVAILABLE, NOT_AVAILABLE, PENDING}	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 Obbligatorio
`condition` enum {EXCELLENT, VERY_GOOD, GOOD, FAIR, POOR, OTHER, NONE}	condition
`currency` ISO 4217 Currency Code	currency Obbligatorio
`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 Obbligatorio
`drivetrain` enum {TWO_WD, FOUR_WD, AWD, FWD, RWD, OTHER, NONE}	drivetrain
`exterior_color` string	exterior_color Obbligatorio
`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 Obbligatorio
`image_url` URL	Obbligatorio
`tags` list<string>
`interior_color` string	interior_color
`make` string	make Obbligatorio
`mileage` JSON object	mileage Obbligatorio
`unit` enum {KILOMETERS, MILES}	Valore predefinito: `"MILES"` unit
`value` int64	Valore predefinito: `0` value
`model` string	model Obbligatorio
`price` int64	price Obbligatorio
`state_of_vehicle` enum {NEW, USED, CPO}	state_of_vehicle Obbligatorio
`title` string	title Obbligatorio
`transmission` enum {AUTOMATIC, MANUAL, OTHER, NONE}	transmission
`trim` string	trim
`url` URI	url Obbligatorio
`vehicle_id` string	vehicle_id Obbligatorio
`vehicle_type` enum {BOAT, CAR_TRUCK, COMMERCIAL, MOTORCYCLE, OTHER, POWERSPORT, RV_CAMPER, TRAILER}	vehicle_type
`vin` string	vin Obbligatorio
`year` int64	year Obbligatorio

Tipo di ricavo

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

Struct {

id: numeric string,

}

Error Codes

Errore	Descrizione
100	Invalid parameter

Aggiornamento

Puoi aggiornare a ProductCatalog effettuando una richiesta POST a /{product_catalog_id}.

Parametri

Parametro	Descrizione
`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	Obbligatorio
`transformation_type` enum{background_cropping_and_padding, background_padding, none}	Obbligatorio
`single_ad` Object	Obbligatorio
`transformation_type` enum{background_cropping_and_padding, background_padding, none}	Obbligatorio
`default_image_url` URL	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	Valore predefinito: `false`
`fallback_image_url` URL	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	Valore predefinito: `false`
`name` UTF-8 encoded 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
`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 Obbligatorio

Tipo di ricavo

Questo endopoint supporta read-after-write e leggerà il nodo in cui hai effettuato una richiesta POST.

Struct {

success: bool,

}

Error Codes

Errore	Descrizione
200	Permissions error
100	Invalid parameter

Eliminazione

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 'access_token=<ACCESS_TOKEN>' \
  -F 'batch=[{"method":"DELETE", "relative_url":"<PRODUCT_CATALOG_ID>/external_event_sources?external_event_sources=["<EXTERNAL_EVENT_SOURCE_ID>"]' \
  https://graph.facebook.com

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

curl -X DELETE \
  -d '0=<PIXEL_ID>' \
  -d '1=<APP_ID>' \
  -d 'access_token=<ACCESS_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

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

Parametri

Parametro Descrizione

Parametro	Descrizione
`allow_delete_catalog_with_live_product_set` boolean	Valore predefinito: `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

allow_delete_catalog_with_live_product_set

boolean

Valore predefinito: 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

Tipo di ricavo

Struct {

success: bool,

}

Error Codes

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

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

Parametri

Parametro Descrizione

Parametro	Descrizione
`user` UID	Business user id or system user id Obbligatorio

user

UID

Business user id or system user id

Obbligatorio

Tipo di ricavo

Struct {

success: bool,

}

Error Codes

Errore	Descrizione
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.