商品标记

您可使用 Instagram 图谱 API 在 Instagram 业务帐户的 Instagram 媒体上创建和管理 Instagram 购物商品标记。

注意：从 2023 年 8 月 10 日开始，一些企业如果不具有已启用结账功能的店铺，将不能再使用内容发布 API 标记其商品。这会影响 API 接口和本地接口，并会移除之前帖子中的商品标记。客户仍可以标记 Facebook 和 Instagram 上启用了结账功能的店铺中的商品。您仍可以参考 shopping_product_tag_eligibility 字段，检查 Instagram 帐户是否有资格使用内容发布 API 标记其商品。

标记商品的一般流程如下：

检查 Instagram 业务帐户是否有资格标记商品。
如果 Instagram 业务帐户有资格，则获取其商品目录。
搜索每个目录以获取符合标记条件的商品。
创建带标记的媒体容器。
发布带标记的媒体容器。

限制

所有内容发布限制均适用于商品标记。
快拍和 Live 不支持商品标记。
Instagram 创作者帐户不支持商品标记。
每个帐户 24 小时内只能发布 25 个带有标记的媒体帖子。轮播相册算作单个帖子。

要求

如需确定各操作所需使用的权限、功能和用户访问口令，请参阅各端点的参考文档。
拥有 Instagram 媒体（待标记）的 Instagram 业务帐户（Instagram 用户）必须拥有通过审核的 Instagram 店铺，且商品目录中有商品。支持应用内及外部 Instagram 店铺结账方式。
应用用户必须在拥有 Instagram 店铺（其商品用于标记媒体）的商务管理平台中具有管理员身份。
为了在应用审核中请求批准多个商品标记端点所需的 instagram_shopping_tag_products 和 catalog_management 权限，您的应用必须与已认证公司相关联。

端点

GET /{ig-user-id} — 检查应用用户的标记资格。
GET /{ig-user-id}/available_catalogs — 获取应用用户的商品目录清单。
GET /{ig-user-id}/catalog_product_search — 获取应用用户目录中符合标记条件的商品清单。
POST /{ig-user-id}/media — 创建带标记的媒体容器（发布流程第 1 步）。
POST /{ig-user-id}/media_publish — 发布带标记的媒体容器（发布流程第 2 步）。
GET /{ig-media-id}/product_tags — 获取已发布 Instagram 媒体上的标记。
DELETE /{ig-media-id}/product_tags — 删除已发布 Instagram 媒体上的标记。
POST /{ig-media-id}/product_tags — 创建或更新已发布 Instagram 媒体上的标记。
GET /{ig-user-id}/product_appeal — 获取商品申诉信息。
POST /{ig-user-id}/product_appeal — 对未通过审核的商品提出申诉。
GET /{ig-media-id}/children — 获取轮播 Instagram 媒体中的子 Instagram 媒体清单。

获取用户资格

在 Instagram 用户端点上请求 shopping_product_tag_eligibility 字段，以确定 Instagram 业务帐户是否已设置 Instagram 店铺。未设置 Instagram 店铺的帐户没有资格标记商品。

GET /{ig-user-id}?fields=shopping_product_tag_eligibility

如果 Instagram 业务帐户已与商务管理平台批准的 Instagram 店铺关联，则返回 true，否则返回 false。

请求示例

curl -i -X GET \
 "https://graph.facebook.com/v19.0/90010177253934?fields=shopping_product_tag_eligibility&access_token=EAAOc..."

响应示例

{
  "shopping_product_tag_eligibility": true,
  "id": "90010177253934"
}

获取目录

您可使用 Instagram 用户可用目录端点获取 Instagram 业务帐户的商品目录。

GET /{ig-user-id}/available_catalogs

系统会返回目录及其元数据数组。响应内容包含以下目录字段：

catalog_id — 目录编号。
catalog_name — 目录名称。
shop_name — 店铺名称。
product_count — 目录中的商品总数。

限制

不支持合作目录，例如购物合作伙伴目录或联盟营销创作者目录。

请求示例

curl -i -X GET \
 "https://graph.facebook.com/v19.0/90010177253934?fields=available_catalogs&access_token=EAAOc..."

响应示例

{
  "available_catalogs": {
    "data": [
      {
        "catalog_id": "960179311066902",
        "catalog_name": "Jay's Favorite Snacks",
        "shop_name": "Jay's Bespoke",
        "product_count": 11
      }
    ]
  },
  "id": "90010177253934"
}

获取符合条件的商品

您可使用 Instagram 用户目录商品搜索端点获取目录中可用于标记媒体的一组商品。支持搜索商品款式。

对于未通过审核的商品，在发布已标记的帖子时，API 不会返回错误，但在此商品通过审核之前发布的帖子上不会显示此标记。因此，建议只有在商品的 review_status 为approved 时，才允许应用用户发布带有该商品标记的帖子。在获取应用用户的符合条件的商品时，系统会默认为每个商品返回此字段。

GET /{ig-user-id}/catalog_product_search

参数

catalog_id — （必要项）目录编号。
q — 要在各商品名称或商品 SKU 编号（目录管理界面的内容编号栏）中搜索的字符串。如果未指定字符串，则系统会返回所有符合标记条件的商品。

系统会返回特定对象，其中包含符合标记条件的商品及其元数据数组。支持基于游标的分页。响应内容包含以下商品字段：

image_url — 商品图片网址。
is_checkout_flow — 如果值为 true，则可在 Instagram 应用中直接购买商品。如果值为 false，则必须在应用用户的应用/网站中购买商品。
merchant_id — 商家编号。
product_id — 商品编号。
product_name — 商品名称。
retailer_id — 零售商编号。
review_status — 审核状态。值可以是：approved、outdated、pending、rejected。通过审核的商品可显示在应用用户的 Instagram 店铺中，但通过审核状态不表示商品库存状态（例如，商品可能处于缺货状态）。只有 review_status 为 approved 的商品所关联的标记可显示在发布的帖子上。
product_variants — 商品款式的商品编号 (product_id) 和款式名称 (variant_name)。

请求示例

curl -i -X GET \
 "https://graph.facebook.com/v19.0/90010177253934/catalog_product_search?catalog_id=960179311066902&q=gummy&access_token=EAAOc..."

响应示例

{
  "data": [
    {
      "product_id": 3231775643511089,
      "merchant_id": 90010177253934,
      "product_name": "Gummy Wombats",
      "image_url": "https://scont...",
      "retailer_id": "oh59p9vzei",
      "review_status": "approved",
      "is_checkout_flow": true,
      "product_variants": [
            {
              "product_id": 5209223099160494
            },
            {
              "product_id": 7478222675582505,
              "variant_name": "Green Gummy Wombats"
            }
          ]
    }
  ]
}

为图片或视频创建带标记的容器

您可使用 Instagram 用户媒体端点创建图片或视频的媒体容器。或者，可参阅为 Reels 创建带标记的媒体容器或轮播。

POST /{ig-user-id}/media

参数

image_url —（仅为图片的必要项）图片的路径。您的图片必须位于公共服务器上。
user_tags —（仅适用于图片）您希望在图片中标记的任何公开 Instagram 用户的公开帐号和 x/y 坐标数组。数组必须采用 JSON 格式，且包含 username、x 和 y 属性。例如 [{username:'natgeo',x:0.5,y:1.0}]。x 和 y 值必须为浮点数，是相对于图片左上角的坐标值，范围为 0.0–1.0。受到标记的用户将在您发布媒体时收到通知。
video_url —（仅为视频的必要项）视频的路径。您的视频必须位于公共服务器上。
thumb_offset —（仅适用于视频）视频封面缩略图的帧位置（以毫秒为单位）。默认值为 0，即视频的第一帧画面。
product_tags —（必要项）对象数组，用于指定要添加到图片或视频中的商品标记。您最多可以为照片和视频动态帖指定 20 个标记，并且最多可以为每个轮播帖指定共计 20 个标记（每张轮播幻灯片 5 个标记）。
- 标记和商品编号必须不得重复。
- 支持表示缺货商品的标记。
- 每个对象均应包含以下信息：
  - product_id —（必要项）商品编号。
  - x —（仅适用于图片）浮点数，表示到已发布媒体图片左侧边缘的距离百分比。值必须在 0.0–1.0 范围内。
- y —（仅适用于图片）浮点数，表示到已发布媒体图片上边缘的距离百分比。值必须在 0.0–1.0 范围内。

如果操作成功，API 将返回容器编号，该编号可用于发布容器。

请求示例

curl -i -X POST \
 "https://graph.facebook.com/v19.0/90010177253934/media?image_url=https%3A%2F%2Fupl...&location_id=7640348500&product_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3231775643511089'%2C%0A%20%20%20%20x%3A%200.5%2C%0A%20%20%20%20y%3A%200.8%0A%20%20%7D%0A%5D&access_token=EAAOc..."

供您参考的 HTML 解码 POST 负载字符串如下：

https://graph.facebook.com/v12.0/90010177253934/media?image_url=https://upl...&location_id=7640348500 &product_tags=[ { product_id:'3231775643511089', x: 0.5, y: 0.8 } ]&access_token=EAAOc...

响应示例

{
  "id": "17969578066508312"
}

为 Reels 创建带标记的媒体容器

您可使用 Instagram 用户媒体端点为 Reels 创建媒体容器。或参阅创建带标记的媒体容器或轮播。

POST /{ig-user-id}/media

参数

media_type — 您必须指定媒体类型 REELS。
video_url — Reels 的视频路径。您的视频必须位于公共服务器上。您的视频必须符合 Reels 规格。
thumb_offset — 视频封面缩略图的帧位置（以毫秒为单位）。默认值为 0，即视频的第一帧画面。
caption — Reels 的说明。
product_tags —（必要项）对象数组，用于指定要添加到 Reels 中的商品标记。您最多可以指定 30 个标记，并且标记和商品编号必须不得重复。支持表示缺货商品的标记。每个对象均应包含以下信息：
- product_id —（必要项）商品编号。
location_id — 与要在视频中标记的地点相关联的公共主页的编号。详情请参阅 Instagram 用户媒体查询字符串参数。
share_to_feed — 设为 true，可请求视频同时出现在“动态”和“Reels”选项卡上。设为 false，可请求视频仅出现在“Reels”选项卡上。
access_token — 您的用户访问口令。

如果操作成功，API 将返回容器编号，该编号可用于发布容器。

请求示例

curl -i -X POST \
 "https://graph.facebook.com/v19.0/90010177253934/media?media_type=REELS&video_url=https://upl...&product_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3231775643511089'%0A%20%20%7D%0A%5D&access_token=EAAOc..."

供您参考的 HTML 解码 POST 负载字符串如下：

https://graph.facebook.com/v12.0/90010177253934/media?media_type=REELS&video_url=https://upl... &product_tags=[ { product_id:'3231775643511089' } ]&access_token=EAAOc...

响应示例

{
  "id": "17969578066508312"
}

发布带标记的媒体容器

您可使用 Instagram 用户媒体发布端点，发布带标记的媒体容器。您在 24 小时内可代表应用用户发布至多 25 个带标记的媒体容器。如要发布轮播，请参阅轮播。只有在商品的 review_status 为 approved 时，与该商品相关联的标记才可显示在发布的帖子上。如果其中任何商品缺货，其标记也会显示在发布的帖子上。

POST /{ig-user-id}/media_publish

参数

creation_id —（必要项）轮播容器编号。

如果操作成功，API 将返回 Instagram 媒体编号。

请求示例

curl -i -X POST \
 "https://graph.facebook.com/v19.0/90010177253934/media_publish?creation_id=17969578066508312&access_token=EAAOc"

响应示例

{
  "id": "90010778325754"
}

获取媒体上的标记

您可使用 Instagram 媒体商品标记端点获取已发布媒体上的标记。

GET /{ig-media-id}/product_tags

系统会返回 Instagram 媒体上的商品标记及其元数据数组。响应内容包含以下商品标记字段：

product_id — 商品编号。
merchant_id — 商家编号。
name — 商品名称。
price_string — 商品价格。
image_url — 商品图片网址。
review_status — 表示商品标记资格状态。值可以是：
approved — 商品已通过审核。
rejected — 商品未通过审核。
pending — 仍在审核中。
outdated — 商品已通过审核，但经过编辑，需要重新审核。
"" — 无审核状态。
no_review — 无审核状态。
is_checkout — 如果值为 true，则可通过 Instagram 应用直接购买商品。如果值为 false，则只能在商家的网站上购买商品。
stripped_price_string — 商品价格短字符串（以限制空格方式显示的价格，例如使用 $100 而非 100 USD）。
string_sale_price_string — 商品售价。
x — 浮点数，表示到媒体图片左侧边缘的距离百分比。值在 0.0–1.0 范围内。
y — 浮点数，表示到媒体图片上边缘的距离百分比。值在 0.0–1.0 范围内。

请求示例

curl -i -X GET \
 "https://graph.facebook.com/v19.0/90010778325754/product_tags?access_token=EAAOc..."

响应示例

{
  "data": [
    {
      "product_id": 3231775643511089,
      "merchant_id": 90010177253934,
      "name": "Gummy Wombats",
      "price_string": "$3.50",
      "image_url": "https://scont...",
      "review_status": "approved",
      "is_checkout": true,
      "stripped_price_string": "$3.50",
      "x": 0.5,
      "y": 0.80000001192093
    }
  ]
}

标记现有媒体

您可使用 Instagram 媒体商品标记端点创建或更新现有 Instagram 媒体上的标记。

POST /{ig-media-id}/product_tags

参数

updated_tags —（必要项）对象数组，用于指定标记图片或视频所用的商品标记（最大值为 5；标记和商品编号必须唯一）。每个对象均应包含以下信息：
product_id —（必要项）商品编号。如果未使用此编号标记 Instagram 媒体，系统将在 Instagram 媒体中添加此标记。如果已使用此编号标记媒体，系统将更新此标记的显示坐标。
x —（仅适用于图片，必要项）浮点数，表示到已发布媒体图片左侧边缘的距离百分比。值必须在 0.0–1.0 范围内。
y —（仅适用于图片，必要项）浮点数，表示到已发布媒体图片上边缘的距离百分比。值必须在 0.0–1.0 范围内。

在达到 5 次标记限制之前，可再次标记媒体。如果在请求时，目标媒体中已带有特定商品标记，则原标记的 x 和 y 值会更新为新值（不会添加新标记）。

如果可以更新商品，系统会返回 true，否则系统会返回 false。

请求示例

curl -i -X POST \
 "https://graph.facebook.com/v19.0/90010778325754/product_tags?updated_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3859448974125379'%2C%0A%20%20%20%20x%3A%200.5%2C%0A%20%20%20%20y%3A%200.8%0A%20%20%7D%0A%5D&access_token=EAAOc..."

供您参考的 HTML 解码 POST 负载字符串如下：

https://graph.facebook.com/v12.0/90010778325754/product_tags?updated_tags=[ { product_id:'3859448974125379', x: 0.5, y: 0.8 } ]&access_token=EAAOc...

响应示例

{
  "success": true
}

删除标记

您可使用 Instagram 媒体商品标记端点删除已发布 Instagram 媒体（包括 Reels）上的标记。

DELETE /{ig-media-id}/product_tags

参数

deleted_tags —（必要项）包含以下要删除的各商品标记信息的数组：
merchant_id —（必要项）商家编号。
product_id —（必要项）商品编号。

如果标记删除成功，系统会返回 true，否则系统会返回 false。

请求示例

curl -i -X DELETE \
 "https://graph.facebook.com/v19.0/90010778325754/product_tags?deleted_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3859448974125379'%2C%0A%20%20%20%20merchant_id%3A'90010177253934'%0A%20%20%7D%0A%5D&access_token=EAAOc..."

供您参考的 HTML 解码 POST 负载字符串如下：

https://graph.facebook.com/v12.0/90010778325754/product_tags?deleted_tags=[ { product_id:'3859448974125379', merchant_id:'90010177253934' } ]&access_token=EAAOc...

响应示例

{
  "success": true
}

对未通过审核的商品提出申诉

您可使用 Instagram 用户商品申诉端点（专为应用用户提供的方式）对未通过审核的商品（其标记无法显示在发布的帖子上）提出申诉。我们建议您为应用用户提供特定申诉方式，以便他们对未通过审核的商品提出申诉，或是建议他们通过商务管理平台提出申诉。

POST /{ig-user-id}/product_appeal

参数

appeal_reason —（必要项）商品应通过审核的原因说明。
product_id —（必要项）商品编号。

如果您的请求已成功送达，系统会返回 true，否则系统会返回 false。响应内容不会表示申诉结果。

请求示例

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/product_appeal?appeal_reason=product%20is%20a%20toy%20and%20not%20a%20real%20weapon&product_id=4382881195057752&access_token=EAAOc..."

响应示例

{
  "success": true
}

获取申诉状态

您可使用 Instagram 用户商品申诉端点获取特定未通过审核的商品的申诉状态：

GET /{ig-user-id}/product_appeal

参数

product_id —（必要项）商品编号。

系统会返回申诉状态元数据。响应内容包含以下申诉字段：

eligible_for_appeal — 表示是否可以对审核决定提出申诉（如果值为 true，则表示可以申诉，如果值为 false，则表示不能申诉）。
product_id — 商品编号。
review_status — 审核状态。值可以是：
approved — 商品已通过审核。
rejected — 商品未通过审核。
pending — 仍在审核中。
outdated — 商品已通过审核，但经过编辑，需要重新审核。
"" — 无审核状态。
no_review — 无审核状态。

请求示例

curl -i -X GET \
 "https://graph.facebook.com/v19.0/90010177253934/product_appeal?product_id=4029274203846188&access_token=EAAOc..."

响应示例

{
  "data": [
    {
      "product_id": 4029274203846188,
      "review_status": "approved",
      "eligible_for_appeal": false
    }
  ]
}

轮播

您可以发布轮播（相册），其中包含的已标记图片、视频或这二者组合的总数不得超过 10。为此，在执行轮播帖子发布流程第 1 步（共 3 步）操作时，只需为要显示在相册轮播中的带标记的各图片或视频创建带标记的媒体容器，然后按照常规步骤继续完成轮播发布流程即可。

获取轮播中的子媒体

若要获取相册轮播中 Instagram 媒体的编号，请使用 Instagram 媒体子端点。