Connect your Facebook Commerce Manager shop to EcomCentral using the Facebook Graph API v18.0 with a long-lived Page Access Token.
Facebook Commerce Manager is the platform that powers selling on Facebook and Instagram through Facebook Shops, Facebook Marketplace for Businesses, and checkout on Facebook. EcomCentral integrates with the Commerce Platform Graph API v18.0 to read orders placed through your Facebook Shop, push shipment tracking information back to buyers, and browse your product catalog.
https://graph.facebook.com/v18.0) and use the same access token — no separate
credentials are needed for the two product areas.
commerce_account_manage_orders and commerce_account_read_orders for
production use. During development you can test with a sandbox Commerce account.
GET https://graph.facebook.com/oauth/access_token?grant_type=fb_exchange_token&client_id={app_id}&client_secret={app_secret}&fb_exchange_token={short_lived_token}GET /me/accounts to list your Pages and copy the Page access token for your Commerce page (Page tokens do not expire unless revoked)access_token credential| Permission | Purpose |
|---|---|
commerce_account_read_orders | List orders and read individual order details, buyer info, and shipping addresses |
commerce_account_manage_orders | Create shipments and push tracking information to buyers |
catalog_management | Read product catalog items and their availability / pricing |
commerce_account_manage_orders and commerce_account_read_orders
require App Review by Facebook before they can be used in production. During
development, test with a sandbox Commerce Manager account or use a test app with test users.
| Key | Required | Description | Example |
|---|---|---|---|
commerce_account_id |
Required | Numeric Commerce Account ID from Commerce Manager → Settings → Business Info | 123456789012345 |
access_token |
Required | Long-lived Page Access Token with the required permissions | EAABsbCS1iHg… |
catalog_id |
Required | Numeric Catalog ID from Commerce Manager → Catalog → Settings | 987654321098765 |
commerceAccountId or page_id
for the Commerce Account ID; accessToken or token for the access token;
catalogId for the Catalog ID.
| Operation | Method | Endpoint |
|---|---|---|
| Test connection | GET | /me?fields=id,name |
| List orders | GET | /{commerce_account_id}/orders?fields=…&limit=N&after={cursor} |
| Order detail | GET | /{order_id}?fields=id,order_status,created,channel,buyer_details,selected_shipping_option,shipping_address,estimated_payment_details,items |
| Add tracking / create shipment | POST | /{order_id}/shipments — JSON body: { carrier, tracking_number, items:[{retailer_id,quantity}] } |
| List products | GET | /{catalog_id}/products?fields=…&limit=N&after={cursor} |
| Product detail | GET | /{product_item_id}?fields=id,retailer_id,name,availability,price,currency,url,image_url |
| Update product availability | POST | /{product_item_id} — form-encoded: availability=…&quantity_to_sell_on_facebook=N |
https://graph.facebook.com/v18.0. The access token is appended as
?access_token={token} (or &access_token={token}) to every request —
no Authorization header is used.
| Status | Meaning |
|---|---|
| Created | Order placed by buyer; awaiting merchant action |
| Processing | Order is being prepared by the merchant |
| In Progress | Order fulfillment is in progress |
| Fulfilled | Order has been dispatched and shipment created |
| In Transit | Package is in transit to the buyer |
| Delivered | Package confirmed delivered to the buyer |
| Cancelled | Order was cancelled (by buyer or merchant) |
| Refunded | Full or partial refund has been issued |
| Feature | Supported | Notes |
|---|---|---|
| View orders (paginated) | ✅ | Order ID, date, status, total; cursor-based pagination |
| View order detail | ✅ | Buyer info, shipping address, shipping method, line items (SKU, qty, price), payment breakdown |
| Add tracking / create shipment | ✅ | Carrier + tracking number required; items built from order detail automatically |
| View products (paginated) | ✅ | Product ID, retailer_id (SKU), name, price, availability; cursor-based pagination |
| View product detail | ✅ | Image, SKU, name, price, availability, link to Facebook listing |
| Update stock quantity | ❌ | Requires a platform-assigned product_item_id, not a SKU/retailer_id — use Commerce Manager or the direct Graph API |
| Test connection | ✅ | Calls GET /me; verifies token is valid and returns the user/page name and ID |
Facebook's Catalog API identifies products by a platform-assigned numeric product_item_id,
not by the merchant's retailer_id (SKU). There is no search-by-SKU endpoint in the Catalog
API, so EcomCentral cannot route stock updates via a SKU lookup. To update availability or quantity,
use Facebook Commerce Manager directly or call
POST /{product_item_id} with your own tooling once you have the product_item_id.
Facebook's Graph API uses cursor-based pagination for both orders and products. The API does not return a total count of records — EcomCentral shows "Page N" but cannot display "of X total". Use the Next and Prev buttons to navigate; the cursor is managed automatically.
Page access tokens do not expire unless revoked, but the underlying user token can expire after 90
days if not refreshed. If you see an OAuthException error, regenerate a long-lived
user token via GET /oauth/access_token?grant_type=fb_exchange_token&…, then
fetch a fresh page token from GET /me/accounts and update the EcomCentral connection.
Your token is missing one of the required permissions. Check that
commerce_account_read_orders, commerce_account_manage_orders, and
catalog_management are all granted to your app and that your app has passed App Review
for the Commerce permissions. In the Graph API Explorer you can check the token's granted scopes
via GET /me/permissions.
A 404 or Invalid node id error on the orders list usually means the
commerce_account_id is incorrect. Verify it in Commerce Manager → Settings → Business
Info. The ID is a long numeric string (typically 15 digits).
A 404 or Invalid node id error on the products list usually means the
catalog_id is incorrect. Verify it in Commerce Manager → Catalog → Settings.