Live Shopping Tools API

Updated: Aug 13, 2026

Copy for LLM

Overview

Use the Live Shopping Tools API to pin and unpin products on Facebook Live videos, and to retrieve product items eligible for pinning. This lets you offer sellers Facebook-native live shopping tools capabilities directly within your application.

Prerequisites

Ensure your sellers have catalogs. Optional: If you are managing the catalogs directly, integrate with Catalog Powered Shopping Features. Complete the setup described in the Catalog Powered Shopping Features documentation. This connects and syncs the seller’s Facebook Page to their product catalog.
Obtain a user access token via Facebook Login for Business or Meta Business Extension (MBE). Your app must use this token to authenticate API calls.
Required permissions:
1. live_shopping_manage_video (required for every Live Shopping Tools API endpoint)
2. catalog_management or pages_manage_posts (Live Shopping Tools API — either permission satisfies this additional check; you do not need both)
3. pages_read_engagement (Live Videos API)
4. pages_show_list (Live Videos API)
5. business_management (required to retrieve a Page access token for Pages in a Business Portfolio)
Page roles:
1. Users must have at least Partial access to the Facebook Page (Content, messages, community activity, ads, insights). Grant this in either place:
  1. On Facebook, go to Settings > Page setup > Page access > People with Facebook access.
  2. In Meta Business Suite settings, grant Partial access to the Facebook Page.

Typical integration flow

Integration flow: the user opens the Live management screen, then either the third-party platform polls product-items or surfaces its own product items list containing Meta product item IDs from catalog sync. Either path leads to the user creating a pre-live playlist, then going live, at which point the platform calls product-list/update to populate the product list, and during the live uses pin, unpin, and pinned-product-item. A seller who goes live without a pre-live playlist goes straight to pin, unpin, and pinned-product-item.

Retrieving the Live Video ID

To use the Live Shopping Tools API, you first need the live video ID for the seller’s active broadcast.

For the API reference, see Live Videos API.

Tip: Use the query parameter broadcast_status=["LIVE"] to filter for actively streaming live videos.

curl -G "https://graph.facebook.com/{page-id}/live_videos?broadcast_status=[\"LIVE\"]&fields=id,video" \
  -H "Authorization: Bearer {access_token}"

Response

Use the id nested inside the video object, not the top-level id.

{
  "data": [
    {
      "id": "1353573280151188",
      "video": {
        "id": "1690911192264916"
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUzMyTEptUlVuVDQ2QU9IUkFDcGdtWWNPRU1hNU41alBnc3BBNGk2TkxIS1ZAFbXdEajlzS053UWgxbEFaWEsxQkFQNVdfRldDYmxVYmJsMnV4dWh3dHhn",
      "after": "QVFIUzMyTEptUlVuVDQ2QU9IUkFDcGdtWWNPRU1hNU41alBnc3BBNGk2TkxIS1ZAFbXdEajlzS053UWgxbEFaWEsxQkFQNVdfRldDYmxVYmJsMnV4dWh3dHhn"
    }
  }
}

Broadcasts that are set up but have not gone live are in an UNPUBLISHED state. To retrieve the live video ID of broadcasts in this state, you need to filter with broadcast_status=["UNPUBLISHED"]. However, broadcasts in this state can only be queried using Page access tokens.

To get a Page access token:

Start with a user access token that meets the minimum requirements listed under “Prerequisites”.
Call /me/accounts to get the list of Pages and their Page access tokens.
Store the Page access token for the Page whose live video ID you need.

Request

Get Page access token:

curl -G "https://graph.facebook.com/me/accounts" \
  -H "Authorization: Bearer {user_access_token}"

Response

{
  "data": [
    {
      "access_token": "<Returned Page Access Token>",
      "category": "Restaurant",
      "category_list": [
        {
          "id": "273819889375819",
          "name": "Restaurant"
        }
      ],
      "name": "Test Page",
      "id": "<page id>",
      "tasks": [
        "MODERATE",
        "MESSAGING",
        "ANALYZE",
        "ADVERTISE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    },
    …
  ]
}

Get an unpublished live video ID

Request

curl -G "https://graph.facebook.com/{page-id}/live_videos?broadcast_status=[\"UNPUBLISHED\"]&fields=id,video" \
  -H "Authorization: Bearer {page_access_token}"

Product pinning API endpoints

1. Get product items

Retrieves product items from the catalogs associated with a live video. Use this to get product item IDs for pinning.

Permissions:

live_shopping_manage_video — always required.
catalog_management / pages_manage_posts — either permission satisfies the check; you do not need both.

Query Parameters:

Parameter	Type	Required	Description
`video_id`	string or integer	Yes	The live video ID.
`search_term`	string	No	Filter products by a keyword. The keyword is matched against the product’s `name` (partial match) and its `retailer_id` (exact match). A product is returned if it matches on either field. Because `retailer_id` is matched exactly, pass the full content ID or SKU to resolve a specific product.
`product_set_ids`	comma-separated string	No	Filter by product set IDs, such as `{product-set-id-1},{product-set-id-2}`.

Example Request:

curl -G "https://api.facebook.com/live-shopping-tools/product-items" \
  -H "Authorization: Bearer {user_access_token}" \
  -d "video_id={live-video-id}" \
  -d "search_term=shirt"

Response:

{
  "data": [
    {
      "id": 7702802353157666,
      "name": "Blue Cotton T-Shirt",
      "description": "Comfortable cotton t-shirt in blue",
      "image_url": "https://example.com/images/blue-shirt.jpg",
      "price": "$19.99",
      "retailer_id": "BLUE-TSHIRT-001",
      "catalog_name": "Spring Collection"
    }
  ]
}

This endpoint returns a maximum of 100 items. Use the search_term parameter to find specific products if your catalog exceeds this limit.

price is a preformatted display string that already includes the currency symbol, for example $19.99 or ฿4,000.00. The symbol reflects the currency of the seller’s catalog. The API does not return a separate ISO currency code, and the exact formatting (symbol placement, thousands separator) depends on request locale. Treat price as display-only — do not parse it to recover a numeric amount or currency.

2. Pin a product

Pins a product to a live video, making it visible to viewers as a featured product.

Permissions:

live_shopping_manage_video — always required.
catalog_management / pages_manage_posts — either permission satisfies the check; you do not need both.

Request Body (JSON):

Field	Type	Required	Description
`video_id`	string or integer	Yes	The live video ID. See Retrieving the Live Video ID.
`product_item_id`	string or integer	Yes	The product item ID to pin. Obtain from the Get Product Items endpoint.

Example Request:

curl -X POST "https://api.facebook.com/live-shopping-tools/pin" \
  -H "Authorization: Bearer {user_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_id": "{live-video-id}",
    "product_item_id": "{product-item-id}"
  }'

Response:

{
  "id": 7702802353157667,
  "name": "Leather Belt",
  "image_url": "https://example.com/images/belt.jpg",
  "price": "$39.99",
  "description": "Genuine leather belt",
  "retailer_id": "LEATHER-BELT-001",
  "catalog_name": "Spring Collection"
}

Calling this endpoint for an already-pinned product succeeds without error.

3. Unpin a product

Removes the currently pinned product from a live video.

Permissions:

live_shopping_manage_video — always required.
catalog_management / pages_manage_posts — either permission satisfies the check; you do not need both.

Request Body (JSON):

Field	Type	Required	Description
`video_id`	string or integer	Yes	The live video ID.

Example Request:

curl -X POST "https://api.facebook.com/live-shopping-tools/unpin" \
  -H "Authorization: Bearer {user_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_id": "{live-video-id}"
  }'

Response:

Success (returns the product that was unpinned)

{
  "id": 7702802353157667,
  "name": "Leather Belt",
  "image_url": "https://example.com/images/belt.jpg",
  "price": "$39.99",
  "description": "Genuine leather belt",
  "retailer_id": "LEATHER-BELT-001",
  "catalog_name": "Spring Collection"
}

Failure (no pinned item)

{
  "title": "No Product Pinned",
  "detail": "No product is currently pinned on this live video.",
  "status": 409
}

4. Get pinned product item

Retrieves the currently pinned (featured) product item on a live video.

Permissions:

live_shopping_manage_video — always required.
catalog_management / pages_manage_posts — either permission satisfies the check; you do not need both.

Query Parameters:

Parameter	Type	Required	Description
`video_id`	string or integer	Yes	The live video ID.

Example Request:

curl -G "https://api.facebook.com/live-shopping-tools/pinned-product-item" \
  -H "Authorization: Bearer {user_access_token}" \
  -d "video_id={live-video-id}"

Response:

{
  "id": 7702802353157666,
  "name": "Blue Cotton T-Shirt",
  "description": "Comfortable cotton t-shirt in blue",
  "image_url": "https://example.com/images/blue-shirt.jpg",
  "price": "$19.99",
  "retailer_id": "BLUE-TSHIRT-001",
  "catalog_name": "Spring Collection"
}

5. Get product list

Retrieves the list of products visible to viewers on a live video. These are products that have been added to the broadcast’s product list, ordered by their pinned sequence number.

Permissions:

live_shopping_manage_video — always required.
catalog_management / pages_manage_posts — either permission satisfies the check; you do not need both.

Query Parameters:

Parameter	Type	Required	Description
`video_id`	string or integer	Yes	The live video ID.

Example Request:

curl -G "https://api.facebook.com/live-shopping-tools/product-list" \
  -H "Authorization: Bearer {user_access_token}" \
  -d "video_id={live-video-id}"

Response:

{
  "data": [
    {
      "id": 7702802353157666,
      "name": "Blue Cotton T-Shirt",
      "description": "Comfortable cotton t-shirt in blue",
      "image_url": "https://example.com/images/blue-shirt.jpg",
      "price": "$19.99",
      "retailer_id": "BLUE-TSHIRT-001",
      "catalog_name": "Spring Collection"
    },
    {
      "id": 7702802353157667,
      "name": "Leather Belt",
      "description": "Genuine leather belt",
      "image_url": "https://example.com/images/belt.jpg",
      "price": "$39.99",
      "retailer_id": "LEATHER-BELT-001",
      "catalog_name": "Spring Collection"
    }
  ]
}

Returns an empty data array if no products have been added to the product list.

6. Update product list

Syncs the product list for a live video. Replaces the current product list with the provided list of product items. Use this to update the product list during a broadcast.

Permissions:

live_shopping_manage_video — always required.
catalog_management / pages_manage_posts — either permission satisfies the check; you do not need both.

Request Body (JSON):

Field	Type	Required	Description
`video_id`	string or integer	Yes	The live video ID.
`product_item_ids`	array of strings or integers	Yes	The product item IDs that make up the new product list.

Example Request:

curl -X PUT "https://api.facebook.com/live-shopping-tools/product-list/update" \
  -H "Authorization: Bearer {user_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_id": "{live-video-id}",
    "product_item_ids": [
      "7702802353157666",
      "7702802353157667",
      "7702802353157668"
    ]
  }'

Response:

{
  "data": [
    {
      "id": 7702802353157666,
      "name": "Blue Cotton T-Shirt",
      "description": "Comfortable cotton t-shirt in blue",
      "image_url": "https://example.com/images/blue-shirt.jpg",
      "price": "$19.99",
      "retailer_id": "BLUE-TSHIRT-001",
      "catalog_name": "Spring Collection"
    },
    {
      "id": 7702802353157667,
      "name": "Leather Belt",
      "description": "Genuine leather belt",
      "image_url": "https://example.com/images/belt.jpg",
      "price": "$39.99",
      "retailer_id": "LEATHER-BELT-001",
      "catalog_name": "Spring Collection"
    },
    {
      "id": 7702802353157668,
      "name": "Sunglasses",
      "description": "UV protection sunglasses",
      "image_url": "https://example.com/images/sunglasses.jpg",
      "price": "$49.99",
      "retailer_id": "SUNGLASSES-001",
      "catalog_name": "Spring Collection"
    }
  ]
}

This endpoint performs a full replacement — any products on the list that are not included in product_item_ids are removed. The response returns the updated product list after the sync.

To clear the product list, pass an empty array:

curl -X PUT "https://api.facebook.com/live-shopping-tools/product-list/update" \
  -H "Authorization: Bearer {user_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_id": "{live-video-id}",
    "product_item_ids": []
  }'

Troubleshooting

Every call fails authorization. Confirm the user holds at least Partial access to the Facebook Page, and that both your App ID and the seller’s Page ID were included in your Beta access request — access is granted per Page.

The endpoint rejects your video_id. You are probably sending the id of the live video object rather than the id nested inside the video object. Use the nested video.id value.

No unpublished broadcasts are returned. UNPUBLISHED broadcasts can only be queried with a Page access token. A user access token returns an empty list rather than an error.

Unpin returns 409 No Product Pinned. Nothing was pinned on that broadcast. This is an expected state, not a failure.