Facebook Page Shops Integration

The Facebook Business Extension, v1 is currently only available to whitelisted Partners. Please contact your Facebook representative for access.

Enable Facebook Page Shops

To enable Facebook Page Shops, specify the canSetupShop parameter in the initial setup. This parameter allows users to select if they want to sync products to a Facebook Page Shops. See Message Passing.

  1. In the product catalog, set the item_group_id parameter. This is applicable for both feed and API approach.
  2. If Shops are enabled, you can specify the checkoutUrl field when uploading products through the feed or API. This url is available as the Checkout on Website button when consumers view the product on the Facebook Shop.

Manage Collections on Facebook Page Shops

You can create and manage Collections on Facebook Page Shops through the API. Collections are a way to organize products of your storefront.

Limitations

  • Availability dependent on Page Shops enablement—Collections are only available if merchant has decided to enable Page Shops. If merchant chooses not to enable Page Shops, the commerce_merchant_settings is unavailable.
  • Limit of 1 collection with 5 products—For a store to be visible, it must have at least one collection and the first collection must have at least 5 products.
  • Collections order—Collections are returned in this order > ascending index, ascending name.
  • All Products—A collection called "All Products" is created by default, and is not mutable. The "All Products" collection contains all products in the catalog and has an ordering index of INT_MAX.

Recommendations

Use the index field on the collection as the default sorting, and within those, sort by name.

Create a Collection

  1. Upon completing the FBE flow, you have the access token and catalog_id.
  2. Make a GET call to retrieve the commerce_merchant_settings:
  3. GET https://graph.facebook.com/v.X.X/<catalog_id>?fields=commerce_merchant_settings{id}
    If the API call only returned the catalog_id, but not the commerce_merchant_settings or its ID, this means that the merchant has not enabled Shops during the Facebook Business Extension setup.

  4. Make a GET call to retrieve the commerce store using the commerce_merchant_settings:
  5. GET https://graph.facebook.com/<commerce_merchant_settings_id>/commerce_store
  6. With the commerce store, you can start to create collections by making POST calls. You get the collection_id as the response result.
POST https://graph.facebook.com/<commerce_store_id>/commerce_store_collections

Parameters

ParameterDescription

filter

type: JSON object

Required.

The filtering rules that need to be set. Empty filter parameter indicates that all product items in the product catalog should be in the set.

name

type: string

Required.

Name of the collection

ordering_index

type: integer

Required.

Order that the collection should appear in the store

visibility

type: enum{PUBLISHED, STAGING}

Required.

Published if the collection should be visible and staging if it should not be visible

default_ordering_item_ids

type: enum{PUBLISHED, STAGING}

Optional.

Array of product_item IDs that defines the order (sequence) of the products in the collection.

Update a Collection

Make a POST call to the collection_id. The parameters are the same as that of creating a collection.

Get Collections

Make a GET call to the commerce_store_collections field.

GET https://graph.facebook.com/<commerce_store_id>?fields=commerce_store_collections

Filter Rules

  • Creating a collection with an empty filter parameter indicates that all product items in the product catalog should be in the set. An empty filter parameter can be specified using either an empty parameter value or an empty JSON object, {}.
  • Filter rules are made up of the following operators and fields:
NameDescription

Operators

Filter Type

and

Conjunction of a list of clauses

or

Disjunction of a list of clauses

i_contains

Contains substring (case insensitive)

i_not_contains

Does not contain substring (case insensitive)

contains

Contains substring (case sensitive)

not_contains

Does not contain substring (case sensitive)

is_any

Value is any of (case sensitive)

is_not_any

Value is not any of (case sensitive)

i_is_any

Value is any of (case insensitive)

i_is_not_any

Value is not any of (case insensitive)

eq

Equal to (case sensitive)

neq

Not equal to (case sensitive)

lt

Less than (numeric fields only)

lte

Less than or equal to (numeric fields only)

gt

Greater than (numeric fields only)

gte

Greater than (numeric fields only)

Data

Data being filtered

availability

Availability of the product item (like "in stock" or "out of stock")

brand

Brand of a product item

category

Category of the product item

condition

Condition of the product item

gender

Gender of the product item

price_amount

Price in cents (4999 denotes $49.99) of a product item

product_feed_id

Facebook ID of the Product Feed of a product item

product_item_id

Facebook ID of a product item

product_group_id

Facebook ID of the Product Group of a product item

product_type

Retailer defined category of a product item

retailer_id

Retailer defined ID of a product item

retailer_product_group_id

Retailer defined ID of a product group

sale_price_amount

Sale price in cents of a product item

  • Each rule is expressed as a JSON-encoded string.

Example Filter Rules

RuleDescription

{"category": {"eq": "Luggage & Bags > Backpacks"}}

Matches all products with the category equal to "Luggage & Bags > Backpacks"

{"retailer_product_id": {"is_any": ["pid1", "pid2"]}}

Matches the products with retailer ID pid1 or pid2

{"or": [{"retailer_product_group_id": {"eq": "group_1"}},{"product_type": {"i_contains": "shirt"}}]}

Matches all products with retailer_product_group_id equal to group_1 or product_type containing shirt