Marketing API Version

Product Catalog Products

Products in a catalog used in Dynamic Ads. See Dynamic Ads, Catalog Setup.

Do not use pagination on this end point. Pagination is incomplete and can result in duplicate or missing products. Do not use it to get a full representation of the product catalog.

For example, fetch the name and catagory of products whose name contains the word shoe:

curl -G \
-d 'fields=["category","name"]' \
-d 'filter={"name":{"i_contains":"shoe"}}' \
-d 'summary=true' \
-d 'access_token=<ACCESS_TOKEN>'
https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/products

The response:

{
  "data": [
    {
      "category": "mens_shoes", 
      "name": "Awesome Mens Shoes in Black", 
      "id": "1234"
    }, 

    ....

    {
      "category": "mens_shoes", 
      "name": "Hipster Mens Shoes in Red", 
      "id": "5678"
    }
  ], 

  ....

  "summary": {
    "total_count": 316
  }
}

Reading

Products that a catalog contains.

You can also filter the results:

Field NameDescriptionTypeRequired

filter

Filter Specification

JSON string

no

Graph API Explorer
GET /v2.10/{product-catalog-id}/products HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{product-catalog-id}/products'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{product-catalog-id}/products",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{product-catalog-id}/products",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{product-catalog-id}/products"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
bulk_pagination
boolean

Used for iterating over the edge in large chunks

filter
A JSON-encoded rule

JSON-encoded WCA rule expression representing the filter to be applied for the edge

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {}, "summary": {} }

data

A list of ProductItem nodes.

paging

For more details about pagination, see the Graph API guide.

summary

Aggregated information about the edge, such as counts. Specify the fields to fetch in the summary param (like summary=total_count).

FieldDescription

total_count

unsigned int32

Total number of products returned by the query

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error

Creating

You can make a POST request to products edge from the following paths:
When posting to this edge, a ProductItem will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
Permissions are not usually requested.

Parameters

NameDescription
additional_image_urls
list<URL>

Additional product image URLs

android_app_name
string

The name of the app (suitable for display)

android_class
string

A fully-qualified Activity class name for intent generation

android_package
string

A fully-qualified package name for intent generation

android_url
string

A custom scheme for the Android app

availability
enum{in stock, out of stock, preorder, available for order, discontinued}
Default value: in stock

Availability of the product item

brand
string

Brand of the product item

category
string

Category of the product item

Required
checkout_url
URL

URL to add product item to cart and directly to checkout

color
string

Color of the product item

condition
enum{new, refurbished, used}
Default value: new

The condition of the product item

currency
ISO 4217 Currency Code

Currency for the product item

Required
custom_data
dictionary { string : <string> }

TBD

custom_label_0
string

An optional custom label to associate with the product item. Max size: 100

custom_label_1
string

An optional custom label to associate with the product item. Max size: 100

custom_label_2
string

An optional custom label to associate with the product item. Max size: 100

custom_label_3
string

An optional custom label to associate with the product item. Max size: 100

custom_label_4
string

An optional custom label to associate with the product item. Max size: 100

description
string

Description of the product item. Max size: 5000

RequiredSupports Emoji
expiration_date
string

Item's expiration date (YYYY-MM-DD)

gender
enum{female, male, unisex}

Gender the product item is targeted towards

gtin
string

Global trade ID of the product item

image_url
URL

URL of the product image

Required
inventory
int64

Inventory count for the product item

ios_app_name
string

The name of the app (suitable for display)

ios_app_store_id
int64

The app ID for the App Store

ios_url
string

A custom scheme for the iOS app

ipad_app_name
string

The name of the app (suitable for display)

ipad_app_store_id
int64

The app ID for the App Store

ipad_url
string

A custom scheme for the iPhone app

iphone_app_name
string

The name of the app (suitable for display)

iphone_app_store_id
int64

The app ID for the App Store

iphone_url
string

A custom scheme for the iPhone app

manufacturer_part_number
string

Manufacturer's ID for the product item

material
string

Material of the product item
Max size: 200

name
string

Name/title of the product item

RequiredSupports Emoji
ordering_index
int64

Index used for ordering items within a group

pattern
string

Pattern of the product item

price
int64

Price of the item with 2 digits added for cents (ex: use "100" for 1 or "599" for 5.99)

Required
product_type
string

Retailer defined category of the product item. Max size: 750

retailer_id
string

A unique identifier for this item (which can be a variant for a product).

Required
retailer_product_group_id
string

Item group ID that this product is a variant of.

sale_price
int64

Sale price of the item with 2 digits added for cents (ex: use "100" for 1 or "599" for 5.99)

sale_price_end_date
datetime

Date when the sale price ends

sale_price_start_date
datetime

Date when the sale price starts

short_description
string

A brief description of the product

size
string

Size of the product item

start_date
string

Date when the product started to exist

url
URL

URL of the product item

Required
visibility
enum{staging, published}
Default value: published

Visibility of the product item

windows_phone_app_id
string

The app ID (a GUID) for app store

windows_phone_app_name
string

The name of the app (suitable for display)

windows_phone_url
string

A custom scheme for the Windows Phone app

Return Type

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

Validation Rules

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

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.