Featured Links API

Updated: Aug 14, 2026

Copy for LLM

What the Featured Links API is and does

The Featured Links API lets your application attach, manage, and display featured links on a Facebook Live video. A featured link is a card shown to viewers during a live broadcast that points to a destination URL — for example a product page, a sign-up form, a booking page, or any web destination you want to promote.

In this initial release, a featured link consists of a title, a destination URL, and an optional image.

The API is part of the broader Live Shopping Tools API, which already lets partners pin catalog product items to live videos. Version 2.0.0 introduces featured links as a new, first-class asset type that sits alongside product items. As a result, the pinning surface is now polymorphic: the asset currently featured on a video can be either a product item or a featured link, and the relevant endpoints return whichever type applies.

In short, the API lets you:

Create featured links on a live video.
Read a single featured link, or list all featured links on a video.
Update a featured link’s destination URL and image.
Delete a featured link.
Reorder the featured links on a video (and remove ones you omit) in a single call.
Pin / unpin an asset (product item or featured link) to a video, and read whatever asset is currently pinned.

What you’ll be able to achieve once integrated

Once your application is integrated, you can build experiences such as:

Drive traffic during live broadcasts. Surface a timely link — a product, a landing page, a promo — as a tappable card while a Page is live.
Promote any web destination. Point viewers to product pages, landing pages, sign-up forms, or booking pages — anything reachable by a URL.
Manage the full lifecycle programmatically. Create links ahead of a broadcast, swap the destination or image on the fly, reorder them, and clean them up afterward.
Build a producer/control-room surface. Read the currently pinned asset and the full list of featured links to render an accurate management UI, then pin/unpin and reorder in response to operator actions.
Support a mixed merchandising model. Because pin/unpin/read are polymorphic, a single control surface can handle both catalog product items and featured links without branching your transport logic.

Prerequisites

Before you can call the Featured Links API, make sure the following are in place.

Permissions (OAuth scopes)

Calls are made with an OAuth access token. Obtain a User/Page Access Token via Facebook Login. The token must carry the right permissions for the operation:

Permission	Required for
`live_shopping_manage_video`	All `/live-shopping-tools/` endpoints.
`pages_manage_engagement`	All featured-link endpoints. Must be granted for the specific Page that owns the live video.
`catalog_management`	Additionally required only when the asset being pinned, unpinned, or read is a catalog product item (not a featured link).
`pages_read_engagement`	Live Video API
`pages_show_list`	Live Video API
`business_management`	To retrieve page access token for pages with Business Portfolio

Page Role(s):

Users need to minimally have Partial access to Facebook Page (Content, messages, community activity, ads, insights). This can be granted either on:

Facebook via Settings > Page setup > Page access > People with Facebook access, or
Meta Business Suite settings page, Partial access to Facebook Page

Supported region

The API enforces regional availability. Requests originating from an unsupported jurisdiction are rejected with 403 Forbidden. Contact your Meta partner representative to learn more.

Seller agreement

The Page that owns the live video must have accepted the Live Shopping Seller Agreement via Facebook Login for Business. Requests on behalf of a Page that has not accepted it are rejected with 403 Seller Agreement Required. Acceptance is a one-time action per Page and is done outside this API.

Quick start

Get onboarded. Have your app and Pages enabled for the Featured Links API (limited availability — contact your Meta partner representative).
Obtain an access token with live_shopping_manage_video and pages_manage_engagement (and catalog_management / pages_manage_posts if you’ll pin catalog product items), for a Page you administer.
Use the Live Video API to obtain the video_id of the live stream (see Retrieving the Live Video ID).
Always sendX-API-Version: 2.0.0 and Authorization: Bearer {ACCESS_TOKEN}.
Create a featured link with POST /featured-link.
Pin it with POST /pin using the returned id as asset_id.
Verify with GET /pinned-item and GET /featured-links.
Reorder or clean up with PUT /featured-links/update, and unpin with POST /unpin when done.

Common error responses

The response body is JSON with title, detail, and status:

{
  "title": "Permission Denied",
  "detail": "You do not have permission to manage the live stream.",
  "status": 403
}

The following errors can be returned by most endpoints:

Status	Title	When
400 Bad Request	Validation error	The request body or parameters are invalid (see per-endpoint details).
403 Forbidden	Region Not Supported	The API is not available in the caller’s jurisdiction.
403 Forbidden	Permission Denied	The acting user can’t manage the Page’s live stream, or a required permission (`live_shopping_manage_video` / `pages_manage_engagement` / `catalog_management`) is not granted.
404 Not Found	Video Not Found	The `video_id` does not exist or is not accessible.
404 Not Found	Endpoint not available	The Page is not enabled for the Featured Links API (see API access).
404 Not Found	Featured Link Not Found	The referenced featured link does not exist or is not accessible (ID-based endpoints).
429 Too Many Requests	Rate limited	The hourly request limit was exceeded.
500 Internal Server Error	Internal Server Error	An unexpected error occurred.

Per-endpoint sections below list the additional, endpoint-specific errors.

Retrieving the Live Video ID

To use the Featured Links API, you first need the live video ID for the seller’s active broadcast.

See the Live Video API for the API reference.

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: be sure to use the id within the video object.

{
  "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, 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 with the minimal requirements stated above under “Prerequisites”.
Call /me/accounts to get the list of pages and their respective page access tokens.
Store the page access token for the page whose live video id you want to retrieve.

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 unpublished live video id:

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

Endpoint reference

Base URL: https://api.facebook.com. Every path in this section is relative to it, for example POST https://api.facebook.com/live-shopping-tools/featured-link. This is not the same host as the Live Video API in Retrieving the Live Video ID, which is served from https://graph.facebook.com.

Every request must include the Authorization and X-API-Version: 2.0.0 headers. Requests with a body must also send Content-Type: application/json.

1. Create a featured link

POST /live-shopping-tools/featured-link

Creates a featured link on a live video.

Permissions:

live_shopping_manage_video — always required.
pages_manage_engagement (for the video’s Page).

Request body

Field	Type	Required	Description
`video_id`	string	Yes	The live video id to attach the link to. See Retrieving the Live Video ID.
`name`	string	Yes	Title of the featured link, shown as the headline on the card.
`url`	string	Yes	Destination URL of the featured link.
`image_url`	string	No	URL of the featured link image.

Response:200 OK — a Featured Link object.

Example request

POST /live-shopping-tools/featured-link
Authorization: Bearer {ACCESS_TOKEN}
X-API-Version: 2.0.0
Content-Type: application/json
{
  "video_id": "1379840474191135",
  "name": "Summer Hat",
  "url": "https://shop.example.com/summer-hat",
  "image_url": "https://cdn.example.com/hat.jpg"
}

Example response

{
  "id": "1234567890",
  "name": "Summer Hat",
  "url": "https://shop.example.com/summer-hat",
  "image_url": "https://cdn.example.com/hat.jpg"
}

2. Get a featured link

GET /live-shopping-tools/featured-link/{id}

Retrieves a single featured link by ID.

Permissions:

live_shopping_manage_video — always required.
pages_manage_engagement (for the link’s Page).

Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	The ID of the featured link to retrieve.

Response:200 OK — a Featured Link object.

Endpoint-specific errors:404 Not Found — “The specified featured link does not exist.” if the ID is unknown or not accessible.

Example

GET /live-shopping-tools/featured-link/1234567890
Authorization: Bearer {ACCESS_TOKEN}
X-API-Version: 2.0.0

3. Update a featured link

PUT /live-shopping-tools/featured-link/{id}

Partially updates a featured link. Only the fields you include are changed; omitted fields keep their current values. The link’s name cannot be changed through this endpoint.

Permissions:

live_shopping_manage_video — always required.
pages_manage_engagement (for the link’s Page).

Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	The ID of the featured link to update.

Request body — all fields optional, but at least one must be provided.

Field	Type	Description
`url`	string	New destination URL.
`image_url`	string	New image URL.

Response:200 OK — the updated Featured Link object.

Endpoint-specific errors

Status	Detail	When
400	At least one updatable field (url, image_url) must be provided.	The request body contains no updatable fields.
404	The specified featured link does not exist.	The ID is unknown or not accessible.

Example

PUT /live-shopping-tools/featured-link/1234567890
Authorization: Bearer {ACCESS_TOKEN}
X-API-Version: 2.0.0
Content-Type: application/json
{
  "url": "https://shop.example.com/summer-hat-v2",
  "image_url": "https://cdn.example.com/hat-v2.jpg"
}

4. Delete a featured link

DELETE /live-shopping-tools/featured-link/{id}

Deletes a featured link.

Permissions:

live_shopping_manage_video — always required.
pages_manage_engagement (for the link’s Page).

Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	The ID of the featured link to delete.

Response:204 No Content — empty body on success.

Endpoint-specific errors

Status	Detail	When
404	The specified featured link does not exist.	The ID is unknown or not accessible.
500	Failed to delete the featured link.	The deletion could not be completed.

Example

DELETE /live-shopping-tools/featured-link/1234567890
Authorization: Bearer {ACCESS_TOKEN}
X-API-Version: 2.0.0

5. List featured links

GET /live-shopping-tools/featured-links

Lists all featured links on a live video. Results are returned in creation order (oldest first).

Permissions:

live_shopping_manage_video — always required.
pages_manage_engagement (for the video’s Page).

Query parameters

Parameter	Type	Required	Description
`video_id`	string	Yes	The live video (broadcast ID or video ID).

Response:200 OK — a Featured Link List object ({ "data": [ … ] }). Returns { "data": [] } when the video has no featured links.

Example request

GET /live-shopping-tools/featured-links?video_id=1379840474191135
Authorization: Bearer {ACCESS_TOKEN}
X-API-Version: 2.0.0

Example response

{
  "data": [
    {
      "id": "1234567890",
      "name": "Summer Hat",
      "url": "https://shop.example.com/summer-hat",
      "image_url": "https://cdn.example.com/hat.jpg"
    }
  ]
}

6. Reorder featured links

PUT /live-shopping-tools/featured-links/update

Sets the order of featured links on a video. The position of each ID in the featured_link_ids array determines its display order.

Important — this call also deletes. Any featured link currently on the video whose ID is not present in featured_link_ids is deleted. To reorder without deleting, include every existing link ID. To delete all links, send an empty array.

Permissions:

live_shopping_manage_video — always required.
pages_manage_engagement (for the video’s Page).

Request body

Field	Type	Required	Description
`video_id`	string	Yes	The live video (broadcast ID or video ID).
`featured_link_ids`	array of strings	Yes	Ordered list of featured link IDs. Position sets display order. IDs on the video but absent from this array are deleted. Must not contain duplicates.

Response:200 OK — a Featured Link List object reflecting the new order.

Endpoint-specific errors

Status	Detail	When
400	featured_link_ids must not contain duplicates.	The array contains a repeated ID.

Example

PUT /live-shopping-tools/featured-links/update
Authorization: Bearer {ACCESS_TOKEN}
X-API-Version: 2.0.0
Content-Type: application/json
{
  "video_id": "1379840474191135",
  "featured_link_ids": ["1234567890", "1234567891"]
}

7. Pin an asset

POST /live-shopping-tools/pin

Pins an asset to a live video so it is featured to viewers. The asset can be either a catalog product item or a featured link — the API detects which from the asset_id.

Permissions:

live_shopping_manage_video — always required.
pages_manage_engagement (for the video’s Page) — always required.
catalog_management / pages_manage_posts — additionally required only when asset_id refers to a catalog product item. Either permission satisfies the check; you do not need both.

Request body

Field	Type	Required	Description
`video_id`	string	Yes	The live video (broadcast ID or video ID) to pin the asset on.
`asset_id`	string	Yes	The ID of the asset to pin — either a product item ID or a featured link ID.

Response:200 OK — a oneOf of Product Item object or Featured Link object, depending on the asset that was pinned. Branch on the shape of the returned object (a Featured Link has a url field; a Product Item does not).

Endpoint-specific errors

Status	Detail	When
400	INVALID_ASSET_ID	asset_id does not match any product item or featured link.
400	ASSET_NOT_ACCESSIBLE	The asset exists but the caller is not allowed to access it.
403	The required permission has not been granted for this operation.	A product item was pinned without catalog_management.

Example

POST /live-shopping-tools/pin
Authorization: Bearer {ACCESS_TOKEN}
X-API-Version: 2.0.0
Content-Type: application/json
{
  "video_id": "1379840474191135",
  "asset_id": "1234567890"
}

8. Unpin the current asset

POST /live-shopping-tools/unpin

Unpins whatever asset is currently featured on the video, so it is no longer shown to viewers. Works whether the pinned asset is a product item or a featured link.

Permissions:

live_shopping_manage_video — always required.
pages_manage_engagement (for the video’s Page) — always required.
catalog_management / pages_manage_posts — additionally required only when the currently pinned asset is a catalog product item. Either permission satisfies the check; you do not need both.

Request body

Field	Type	Required	Description
`video_id`	string	Yes	The live video (broadcast ID or video ID) to unpin the asset from.

Response:200 OK — a oneOf of Product Item object or Featured Link object representing the asset that was unpinned.

Endpoint-specific errors

Status	Detail	When
409 Conflict	No asset is currently pinned on this live video.	Nothing is pinned, so there is nothing to unpin.

Example

POST /live-shopping-tools/unpin
Authorization: Bearer {ACCESS_TOKEN}
X-API-Version: 2.0.0
Content-Type: application/json
{
  "video_id": "1379840474191135"
}

9. Get the pinned asset

GET /live-shopping-tools/pinned-item

Returns the asset currently pinned on a live video — a product item or a featured link — or null if nothing is pinned.

Permissions:

live_shopping_manage_video — always required.
pages_manage_engagement (for the video’s Page) — always required.
catalog_management / pages_manage_posts — additionally required only when the currently pinned asset is a catalog product item. Either permission satisfies the check; you do not need both.

Query parameters

Parameter	Type	Required	Description
`video_id`	string	Yes	The live video (broadcast ID or video ID).

Response:200 OK — a oneOf of Product Item object or Featured Link object, or null when no asset is pinned.

Example

GET /live-shopping-tools/pinned-item?video_id=1379840474191135
Authorization: Bearer {ACCESS_TOKEN}
X-API-Version: 2.0.0

Troubleshooting

Every call returns 404 Not Found. The Page is not yet enabled for the Featured Links API. Access is granted per Page and per App — contact your Meta partner representative with your App ID and the Page IDs you need onboarded.

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

Updating a featured link returns 400. The request body must contain at least one of url or image_url. The link’s name cannot be changed through this endpoint.

A reorder call removed featured links.PUT /featured-links/update deletes any link on the video whose ID is absent from featured_link_ids. Include every ID you want to keep.

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