Версия 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.

Чтение

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

Параметры

Параметр Описание

Параметр	Описание
`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, CREATORS_AS_SELLERS, 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, CREATORS_AS_SELLERS, DIGITAL_CIRCULARS, FB_LIVE_SHOPPING, IG_SHOPPING, IG_SHOPPING_SUGGESTED_PRODUCTS, MARKETPLACE_SHOPS, TEST}>

segment_use_cases

Поля

Поле	Описание
`id` numeric string	ID of a catalog По умолчанию
`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 По умолчанию
`product_count` int32	The total number of products in a catalog
`vertical` enum	The type of catalog (for example: hotels, commerce, etc)

Границы контекста

Граница контекста	Описание
`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

Ошибка	Описание
100	Invalid parameter
368	The action attempted has been deemed abusive or is otherwise disallowed
190	Invalid OAuth 2.0 Access Token
2635	You are calling a deprecated version of the Ads API. Please update to the latest version.

Создание

Examples

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

Вы можете сделать запрос POST к границе vehicles из этих местоположений:

/{product_catalog_id}/vehicles

При размещении публикации на этой границе создается a ProductCatalog.

Параметры

Параметр	Описание
`address` JSON object	address Обязательно
`city` string	Значение по умолчанию: `""` city
`city_id` string	city_id
`country` string	Значение по умолчанию: `""` country
`latitude` float	latitude
`longitude` float	longitude
`neighborhoods` array<string>	neighborhoods
`postal_code` string	Значение по умолчанию: `""` postal_code
`region` string	Значение по умолчанию: `""` region
`street_address` string	Значение по умолчанию: `""` 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 Обязательно
`condition` enum {EXCELLENT, VERY_GOOD, GOOD, FAIR, POOR, OTHER, NONE}	condition
`currency` ISO 4217 Currency Code	currency Обязательно
`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 Обязательно
`drivetrain` enum {TWO_WD, FOUR_WD, AWD, FWD, RWD, OTHER, NONE}	drivetrain
`exterior_color` string	exterior_color Обязательно
`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 Обязательно
`image_url` URL	Обязательно
`tags` list<string>
`interior_color` string	interior_color
`make` string	make Обязательно
`mileage` JSON object	mileage Обязательно
`unit` enum {KILOMETERS, MILES}	Значение по умолчанию: `"MILES"` unit
`value` int64	Значение по умолчанию: `0` value
`model` string	model Обязательно
`price` int64	price Обязательно
`state_of_vehicle` enum {NEW, USED, CPO}	state_of_vehicle Обязательно
`title` string	title Обязательно
`transmission` enum {AUTOMATIC, MANUAL, OTHER, NONE}	transmission
`trim` string	trim
`url` URI	url Обязательно
`vehicle_id` string	vehicle_id Обязательно
`vehicle_type` enum {BOAT, CAR_TRUCK, COMMERCIAL, MOTORCYCLE, OTHER, POWERSPORT, RV_CAMPER, TRAILER}	vehicle_type
`vin` string	vin Обязательно
`year` int64	year Обязательно

Тип возврата

Эта конечная точка поддерживаетчтение после записи и будет считывать узел, представленный id в типе возврата.

Struct {

id: numeric string,

}

Error Codes

Ошибка	Описание
200	Permissions error

Вы можете сделать запрос POST к границе items_batch из этих местоположений:

/{product_catalog_id}/items_batch

При размещении публикации на этой границе создается a ProductCatalog.

Параметры

Параметр	Описание
`allow_upsert` boolean	Значение по умолчанию: `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}	Значение по умолчанию: `"EMPTY"` The sub vertical type of items in the request
`item_type` string	The type of items in the request Обязательно
`requests` JSON object	Array of JSON objects containing batch requests. Each batch request consists of `method` and `data` fields Обязательно

Тип возврата

Эта конечная точка поддерживает чтение после записи и будет считывать узел, в который вы сделали публикацию.

Struct {

handles: List [

string

validation_status: List [

Struct {

errors: List [

Struct {

message: string,

}

retailer_id: string,

warnings: List [

Struct {

message: string,

}

Error Codes

Ошибка	Описание
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

Вы можете сделать запрос POST к границе owned_product_catalogs из этих местоположений:

/{business_id}/owned_product_catalogs

При размещении публикации на этой границе создается a ProductCatalog.

Параметры

Параметр	Описание
`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	Обязательно
`transformation_type` enum{background_cropping_and_padding, background_padding, none}	Обязательно
`single_ad` Object	Обязательно
`transformation_type` enum{background_cropping_and_padding, background_padding, none}	Обязательно
`destination_catalog_settings` JSON object	Destination catalog settings.
`generate_items_from_pages` boolean	Значение по умолчанию: `false`
`flight_catalog_settings` JSON object	Flight catalog settings.
`generate_items_from_events` boolean	Значение по умолчанию: `false`
`name` UTF-8 encoded string	Name of the catalog. Обязательно
`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` page ID	page_id Обязательно
`vertical` enum {adoptable_pets, commerce, destinations, flights, generic, home_listings, hotels, jobs, local_service_businesses, offer_items, offline_commerce, transactable_items, vehicles}	Значение по умолчанию: `commerce` The catalog's industry or vertical, such as `commerce`.

Тип возврата

Struct {

id: numeric string,

}

Error Codes

Ошибка	Описание
100	Invalid parameter
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.
200	Permissions error

Вы можете сделать запрос POST к границе assigned_users из этих местоположений:

/{product_catalog_id}/assigned_users

При размещении публикации на этой границе создается a ProductCatalog.

Параметры

Параметр Описание

Параметр	Описание
`tasks` array<enum {MANAGE, ADVERTISE, MANAGE_AR, AA_ANALYZE}>	Catalog permission tasks to assign this user Обязательно
`user` UID	Business user id or system user id Обязательно

tasks

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

Catalog permission tasks to assign this user

Обязательно

user

UID

Business user id or system user id

Обязательно

Тип возврата

Эта конечная точка поддерживает чтение после записи и будет считывать узел, в который вы сделали публикацию.

Struct {

success: bool,

}

Error Codes

Ошибка	Описание
100	Invalid parameter
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.
200	Permissions error
190	Invalid OAuth 2.0 Access Token

Обновление

Чтобы обновить a ProductCatalog, отправьте запрос POST на адрес /{product_catalog_id}.

Параметры

Параметр	Описание
`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	Обязательно
`transformation_type` enum{background_cropping_and_padding, background_padding, none}	Обязательно
`single_ad` Object	Обязательно
`transformation_type` enum{background_cropping_and_padding, background_padding, none}	Обязательно
`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	Значение по умолчанию: `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	Значение по умолчанию: `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` page ID	page_id Обязательно

Тип возврата

Эта конечная точка поддерживает чтение после записи и будет считывать узел, в который вы сделали публикацию.

Struct {

success: bool,

}

Error Codes

Ошибка	Описание
100	Invalid parameter
200	Permissions error

Удаление

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

Параметры

Параметр Описание

Параметр	Описание
`allow_delete_catalog_with_live_product_set` boolean	Значение по умолчанию: `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

Значение по умолчанию: 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

Тип возврата

Struct {

success: bool,

}

Error Codes

Ошибка	Описание
3970	You must be assigned as an admin of this product catalog before you can delete it.
100	Invalid parameter
801	Invalid operation
190	Invalid OAuth 2.0 Access Token

Вы можете отменить связывание a ProductCatalog и a ProductCatalog, отправив запрос DELETE на адрес /{product_catalog_id}/assigned_users.

Параметры

Параметр Описание

Параметр	Описание
`user` UID	Business user id or system user id Обязательно

user

UID

Business user id or system user id

Обязательно

Тип возврата

Struct {

success: bool,

}

Error Codes

Ошибка	Описание
100	Invalid parameter
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.