API Marketing
Phiên bản API Đồ thị

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.

Đọc

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

Thông số

Thông sốMô tả
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

Trường

Trường thông tinMô tả
id
numeric string

ID of a catalog

Mặc định
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

Mặc định
product_count
int32

The total number of products in a catalog

vertical
enum

The type of catalog (for example: hotels, commerce, etc)

Đường viền

CạnhMô tả
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

Mã lỗi

LỗiMô tả
100Invalid parameter
368The action attempted has been deemed abusive or is otherwise disallowed
190Invalid OAuth 2.0 Access Token
200Permissions error
80009There 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.
2500Error parsing graph query

Tạo

Examples

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

Bạn có thể tạo yêu cầu POST đến cạnh items_batch từ các đường dẫn sau:
Khi đăng lên cạnh này, hệ thống sẽ tạo a ProductCatalog.

Thông số

Thông sốMô tả
allow_upsert
boolean
Giá trị mặc định: 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}
Giá trị mặc định: "EMPTY"

The sub vertical type of items in the request

item_type
string

The type of items in the request

Bắt buộc
requests
JSON object

Array of JSON objects containing batch requests. Each batch request consists of method and data fields

Bắt buộc

Kiểu trả về

Điểm cuối này hỗ trợ đọc sau khi ghi và sẽ đọc nút mà bạn đã đăng vào đó.
Struct {
handles: List [
string
],
validation_status: List [
Struct {
errors: List [
Struct {
message: string,
}
],
retailer_id: string,
warnings: List [
Struct {
message: string,
}
],
}
],
}

Mã lỗi

LỗiMô tả
80014There 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.
100Invalid parameter
200Permissions error
190Invalid OAuth 2.0 Access Token
368The action attempted has been deemed abusive or is otherwise disallowed
Bạn có thể tạo yêu cầu POST đến cạnh owned_product_catalogs từ các đường dẫn sau:
Khi đăng lên cạnh này, hệ thống sẽ tạo a ProductCatalog.

Thông số

Thông sốMô tả
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

Bắt buộc
transformation_type
enum{background_cropping_and_padding, background_padding, none}

Bắt buộc
single_ad
Object

Bắt buộc
transformation_type
enum{background_cropping_and_padding, background_padding, none}

Bắt buộc
destination_catalog_settings
JSON object

Destination catalog settings.

generate_items_from_pages
boolean
Giá trị mặc định: false

flight_catalog_settings
JSON object

Flight catalog settings.

generate_items_from_events
boolean
Giá trị mặc định: false

name
UTF-8 encoded string

Name of the catalog.

Bắt buộc
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

Bắt buộc
vertical
enum {adoptable_pets, commerce, destinations, flights, generic, home_listings, hotels, jobs, local_service_businesses, offer_items, offline_commerce, transactable_items, vehicles}
Giá trị mặc định: commerce

The catalog's industry or vertical, such as commerce.

Kiểu trả về

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Mã lỗi

LỗiMô tả
100Invalid parameter
200Permissions error
2310068Cannot create a catalog segment from a non CPAS compliant parent catalog
415Two 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.
Bạn có thể tạo yêu cầu POST đến cạnh assigned_users từ các đường dẫn sau:
Khi đăng lên cạnh này, hệ thống sẽ tạo a ProductCatalog.

Thông số

Thông sốMô tả
tasks
array<enum {MANAGE, ADVERTISE, MANAGE_AR, AA_ANALYZE}>

Catalog permission tasks to assign this user

Bắt buộc
user
UID

Business user id or system user id

Bắt buộc

Kiểu trả về

Điểm cuối này hỗ trợ đọc sau khi ghi và sẽ đọc nút mà bạn đã đăng vào đó.
Struct {
success: bool,
}

Mã lỗi

LỗiMô tả
100Invalid parameter
200Permissions error
Bạn có thể tạo yêu cầu POST đến cạnh vehicles từ các đường dẫn sau:
Khi đăng lên cạnh này, hệ thống sẽ tạo a ProductCatalog.

Thông số

Thông sốMô tả
address
JSON object

address

Bắt buộc
city
string
Giá trị mặc định: ""

city

city_id
string

city_id

country
string
Giá trị mặc định: ""

country

latitude
float

latitude

longitude
float

longitude

neighborhoods
array<string>

neighborhoods

postal_code
string
Giá trị mặc định: ""

postal_code

region
string
Giá trị mặc định: ""

region

street_address
string
Giá trị mặc định: ""

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

Bắt buộc
condition
enum {EXCELLENT, VERY_GOOD, GOOD, FAIR, POOR, OTHER, NONE}

condition

currency
ISO 4217 Currency Code

currency

Bắt buộc
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

Bắt buộc
drivetrain
enum {TWO_WD, FOUR_WD, AWD, FWD, RWD, OTHER, NONE}

drivetrain

exterior_color
string

exterior_color

Bắt buộc
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

Bắt buộc
image_url
URL

Bắt buộc
tags
list<string>

interior_color
string

interior_color

make
string

make

Bắt buộc
mileage
JSON object

mileage

Bắt buộc
unit
enum {KILOMETERS, MILES}
Giá trị mặc định: "MILES"

unit

value
int64
Giá trị mặc định: 0

value

model
string

model

Bắt buộc
price
int64

price

Bắt buộc
state_of_vehicle
enum {NEW, USED, CPO}

state_of_vehicle

Bắt buộc
title
string

title

Bắt buộc
transmission
enum {AUTOMATIC, MANUAL, OTHER, NONE}

transmission

trim
string

trim

url
URI

url

Bắt buộc
vehicle_id
string

vehicle_id

Bắt buộc
vehicle_type
enum {BOAT, CAR_TRUCK, COMMERCIAL, MOTORCYCLE, OTHER, POWERSPORT, RV_CAMPER, TRAILER}

vehicle_type

vin
string

vin

Bắt buộc
year
int64

year

Bắt buộc

Kiểu trả về

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Mã lỗi

LỗiMô tả
100Invalid parameter

Cập nhật

Bạn có thể cập nhật a ProductCatalog bằng cách thực hiện yêu cầu POST đến /{product_catalog_id}.

Thông số

Thông sốMô tả
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

Bắt buộc
transformation_type
enum{background_cropping_and_padding, background_padding, none}

Bắt buộc
single_ad
Object

Bắt buộc
transformation_type
enum{background_cropping_and_padding, background_padding, none}

Bắt buộc
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
Giá trị mặc định: 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
Giá trị mặc định: 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

Bắt buộc

Kiểu trả về

Điểm cuối này hỗ trợ đọc sau khi ghi và sẽ đọc nút mà bạn đã đăng vào đó.
Struct {
success: bool,
}

Mã lỗi

LỗiMô tả
200Permissions error
100Invalid parameter

Xóa

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

Thông số

Thông sốMô tả
allow_delete_catalog_with_live_product_set
boolean
Giá trị mặc định: 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

Kiểu trả về

Struct {
success: bool,
}

Mã lỗi

LỗiMô tả
801Invalid operation
3970You must be assigned as an admin of this product catalog before you can delete it.
100Invalid parameter
Bạn có thể hủy liên kết a ProductCatalog khỏi a ProductCatalog bằng cách thực hiện yêu cầu DELETE đến /{product_catalog_id}/assigned_users.

Thông số

Thông sốMô tả
user
UID

Business user id or system user id

Bắt buộc

Kiểu trả về

Struct {
success: bool,
}

Mã lỗi

LỗiMô tả
415Two 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.