圖形 API 版本

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

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

/{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

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

/{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 必填

傳回類型

此端點支援寫入後讀取功能，並將讀取你傳送 POST 的節點。

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

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

/{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`.

傳回類型

此端點支援寫入後讀取功能，並將讀取傳回類型表示為 id 的節點。

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

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

/{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

必填

傳回類型

此端點支援寫入後讀取功能，並將讀取你傳送 POST 的節點。

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

更新中

你可以向 /{product_catalog_id} 提出發佈要求，以更新 a ProductCatalog 。

參數

參數	說明
`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 必填

傳回類型

此端點支援寫入後讀取功能，並將讀取你傳送 POST 的節點。

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

你可以向 /{product_catalog_id} 提出刪除要求，以刪除 a ProductCatalog 。

參數

參數說明

參數	說明
`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

你可以向 /{product_catalog_id}/assigned_users 提出刪除要求，中斷 a ProductCatalog 和 a ProductCatalog 的關聯。

參數

參數說明

參數	說明
`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.