Instagramプラットフォーム

商品タグ付け

InstagramグラフAPIを使って、InstagramビジネスのIGメディアに対してInstagramショッピング商品タグを作成し管理することができます。

注: 2023年8月10日より、チェックアウト可能なショップを持たない一部のビジネスは、コンテンツ公開APIを使用って商品にタグ付けすることができなくなります。これはAPIとネイティブインターフェイスの両方に影響を及ぼし、過去の投稿から製品へのタグが削除されます。FacebookとInstagramでチェックアウトを有効にしておけば、顧客は引き続きショップの商品をタグ付けできます。Instagramアカウントがコンテンツ公開APIを使用して商品をタグ付けできるかどうか、引き続きshopping_product_tag_eligibilityフィールドを参照して確認できます。

商品タグ付けの一般的な流れは、次のとおりです。

  1. Instagramビジネスに商品タグ付けを利用する資格があるかどうか確認します。
  2. 資格がある場合は、その商品カタログを取得します。
  3. タグ付けを利用できる商品を各カタログから検索します。
  4. タグ付きメディアコンテナを作成します。
  5. タグ付きメディアコンテナを公開します。

制限

  • すべてのコンテンツ公開の制限が商品のタグ付けに適用されます。
  • ストーリーズとライブでは、商品タグ付けはサポートされていません。
  • Instagramクリエイターアカウントでは、商品タグ付けはサポートされていません。
  • アカウントには、タグ付きメディア投稿が24時間以内に25件までという制限があります。カルーセルアルバムは1件の投稿としてカウントされます。

要件

  • それぞれの操作にどのアクセス許可、機能、ユーザーアクセストークンが必要かについては、各エンドポイントのリファレンスドキュメントをご覧ください。
  • (タグ付け対象の) IGメディアを所有するInstagramビジネスアカウント(IGユーザー)は、承認済みのInstagramショップと、商品が含まれている商品カタログを持っていなければなりません。Instagramショップでは、アプリ内とアプリ外のチェックアウト方法がサポートされています。
  • アプリユーザーは、ビジネスマネージャで管理者権限を持っていなければなりません。この管理者は、メディアへのタグ付けに使用されている商品を販売するInstagramショップのオーナーとなります。
  • 商品タグ付けの複数のエンドポイントで必要とされるinstagram_shopping_tag_productsとcatalog_managementのアクセス許可に関するアプリレビューの承認をリクエストするには、アプリが認証されたビジネスに関連付けられていなければなりません。

エンドポイント

ユーザーの資格を確認する

InstagramビジネスアカウントがInstagramショップを設定しているかどうかを確認するため、IGユーザーエンドポイントでshopping_product_tag_eligibilityフィールドをリクエストします。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"
}

カタログを取得する

IGユーザー利用可能カタログエンドポイントを使って、Instagramビジネスアカウントの商品カタログを取得します。

GET /{ig-user-id}/available_catalogs

カタログとそのメタデータの配列を返します。応答には、以下のカタログフィールドが含まれることがあります。

  • catalog_id — カタログ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"
}

対象商品を取得する

IGユーザーカタログ商品検索エンドポイントカタログからメディアのタグ付けに使うことのできる商品のコレクションを取得します。商品バリエーションがサポートされています。

未承認の商品にタグが付いている投稿を公開してもAPIからエラーは返されませんが、商品が承認されるまでは、公開された投稿にタグは表示されません。したがって、アプリユーザーに公開を許可する投稿は、商品のreview_statusがapprovedであるタグの付いたものだけにするようおすすめします。このフィールドは、アプリユーザーの対象商品を取得した時点で、デフォルトで商品ごとに返されます。

GET /{ig-user-id}/catalog_product_search

パラメーター

  • catalog_id — (必須) カタログID。
  • q — 各商品名または商品のSKU番号の中から検索する文字列(カタログ管理インターフェイスの[Content ID (コンテンツID)]コラム)。文字列が指定されていない場合、タグ付け可能な商品すべてが返されます。

タグ付け対象商品とそのメタデータの配列を含むオブジェクトを返します。カーソルによるページ移動がサポートされています。応答には、以下の商品フィールドが含まれることがあります。

  • image_url — 商品画像のURL。
  • is_checkout_flow — trueなら、Instagramアプリの中で直接商品を購入できます。falseなら、アプリユーザーのアプリ/ウェブサイトの中で商品を購入する必要があります。
  • merchant_id — 販売者ID。
  • product_id — 商品ID。
  • product_name — 商品名。
  • retailer_id — 小売店ID。
  • review_status — 審査ステータス。可能な値は、approved、outdated、pending、rejectedです。承認された商品はアプリユーザーのInstagramショップに表示可能ですが、承認済みステータスは商品の在庫があることを示すものではありません(商品が在庫切れの場合もあります)。公開された投稿に表示されるタグは、review_statusがapprovedの商品に関連するものだけです。
  • product_variants — 商品バリエーションの商品ID (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"
            }
          ]
    }
  ]
}

画像または動画のタグ付きコンテナを作成する

IGユーザーメディアエンドポイントを使って、画像または動画のメディアコンテナを作成します。または、リールのタグ付きメディアコンテナを作成するまたはカルーセルをご覧ください。

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個のタグ)を指定できます。
    • タグと商品IDは一意である必要があります。
    • 在庫切れ商品に対するタグがサポートされています。
    • 各オブジェクトで以下の情報が必要です。
      • product_id — (必須) 商品ID。
      • x — (画像のみ)公開メディア画像の左境界からの距離をパーセントで示す浮動小数点数。0.0以上1.0以下の範囲の値でなければなりません。
    • y — (画像のみ)公開メディア画像の上境界からの距離をパーセントで示す浮動小数点数。0.0以上1.0以下の範囲の値でなければなりません。

処理が成功すると、APIからコンテナIDが返されます。このコンテナIDは、コンテナを公開する際に使うことができます。

リクエストの例

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"
}

リールのタグ付きコンテナを作成する

IGユーザーメディアエンドポイントを使って、リールのメディアコンテナを作成します。または、タグ付きメディアコンテナを作成するまたはカルーセルをご覧ください。

POST /{ig-user-id}/media

パラメーター

  • media_type — メディアタイプREELSを指定する必要があります。
  • video_url — リール動画のパス。動画は公開サーバー上になければなりません。動画はリールの仕様を満たしていなければなりません。
  • thumb_offset — (動画のみ)動画のカバーサムネイル画像に使うフレームの位置(ミリ秒)。デフォルト値は0であり、動画の最初のフレームを表します。
  • caption — リールのキャプション。
  • product_tags — (必須)リールに追加する商品タグを指定するオブジェクトの配列。最大30件のタグを指定できます。タグと商品IDは一意でなければなりません。在庫切れ商品に対するタグがサポートされています。各オブジェクトで以下の情報が必要です。
    • product_id — (必須)商品ID。
  • location_id — 動画にタグ付けする所在地に関連したページのID。詳しくは、IGユーザーメディアのクエリ文字列パラメーターをご覧ください。
  • share_to_feed — [フィード]タブと[リール]タブの両方に動画が表示されるようリクエストするにはtrue。[リール]タブでのみ動画が表示されるようリクエストするにはfalse。
  • access_token — ユーザーアクセストークン。

処理が成功すると、APIからコンテナIDが返されます。コンテナを公開する際に、このコンテナIDを使うことができます。

リクエストの例

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"
}

タグ付きメディアコンテナを公開する

IGユーザーメディア公開エンドポイントを使って、タグ付きメディアコンテナを公開します。アプリユーザーのためにタグ付きメディアコンテナを、24時間の移動時間枠内に25個まで公開できます。カルーセルを公開する場合は、カルーセルをご覧ください。公開済み投稿に表示されるのは、review_statusがapprovedの商品だけです。それらの商品のいずれかが在庫切れの場合も、そのタグは引き続き公開済み投稿に表示されたままになります。

POST /{ig-user-id}/media_publish

パラメーター

  • creation_id — (必須)カルーセルコンテナID。

処理が成功した場合、APIからIGメディアIDが返されます。

リクエストの例

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

応答の例

{
  "id": "90010778325754"
}

メディアに付けられたタグを取得する

IGメディア商品タグエンドポイントを使って、公開済みIGメディアに付けられたタグを取得します。

GET /{ig-media-id}/product_tags

IGメディアに付けられた商品タグとそのメタデータの配列が返されます。応答には、以下の商品タグフィールドが含まれることがあります。

  • product_id — 商品ID。
  • merchant_id — 販売者ID。
  • name — 商品名。
  • price_string — 商品の価格。
  • image_url — 商品画像のURL。
  • review_status — 商品タグの資格ステータスを示します。値は次のいずれかです。
  • approved — 商品は承認済みです。
  • rejected — 商品は却下されました。
  • pending — まだ審査中です。
  • outdated — 商品は承認されましたが、その後編集されたため再承認が必要です。
  • "" — 審査ステータスなし。
  • no_review — 審査ステータスなし。
  • is_checkout — trueなら、Instagramアプリを通じて直接商品を購入できます。falseなら、商品は販売者のウェブサイト上でのみ購入可能です。
  • stripped_price_string — 商品の短縮価格文字列(スペースに制約がある場合の価格。100 USDの代わりに$100と表示するなど)。
  • 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
    }
  ]
}

既存のメディアにタグ付けする

IGメディア商品タグエンドポイントを使って、既存のIGメディアに対してタグを作成したり更新したりします。

POST /{ig-media-id}/product_tags

パラメーター

  • updated_tags — (必須)画像または動画にどの商品タグを付けるかを指定するオブジェクトの配列(最大5。タグと商品IDは一意でなければなりません)。各オブジェクトで以下の情報が必要です。
  • product_id — (必須)商品ID。IGメディアにこのIDでタグ付けされていない場合、タグがそのIGメディアに追加されます。メディアにこのIDでのタグ付けがすでになされている場合、タグの表示座標が更新されます。
  • 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
}

タグを削除する

IGメディア商品タグエンドポイントを使って、リールを含め、公開済みIGメディアに付けられたタグを削除します。

DELETE /{ig-media-id}/product_tags

パラメーター

  • deleted_tags — (必須)削除する商品タグごとに以下の情報が含まれる配列。
  • merchant_id — (必須)販売者ID。
  • product_id — (必須)商品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
}

商品却下について異議を申し立てる

商品却下について異議を申し立てるための手段をアプリユーザーに提供する場合は、IGユーザー商品異議申し立てエンドポイントを使います(却下された商品のタグは公開済み投稿に表示されません)。必須ではありませんが、アプリユーザーに対して却下への異議を申し立てるための手段を提供するか、ビジネスマネージャを使って却下への異議を申し立てるよう提案することをおすすめします。

POST /{ig-user-id}/product_appeal

パラメーター

  • appeal_reason — (必須)商品の承認を主張する理由。
  • product_id — (必須)商品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
}

異議申し立てステータスを取得する

IGユーザー商品異議申し立てエンドポイントを使って、却下された特定の商品についての異議申し立てのステータスを取得します。

GET /{ig-user-id}/product_appeal

パラメーター

  • product_id — (必須)商品ID。

異議申し立てステータスメタデータを返します。応答には、以下の異議申し立てフィールドが含まれることがあります。

  • eligible_for_appeal — 審査結果について異議申し立てが可能かどうかを示します(可能な場合はtrue、可能でない場合はfalse)。
  • product_id — 商品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個まで含むカルーセル(アルバム)を公開できます。そのためには、カルーセル投稿公開プロセスの3つのうち1番目のステップを実行する際に、アルバムカルーセルに表示するタグ付けされた各画像または各動画のタグ付けメディアコンテナを作成してから、カルーセル公開プロセスを通常通りに続行します。

カルーセル内の子メディアを取得する

アルバムカルーセルのIGメディアのIDを取得するには、IGメディア子エンドポイントを使います。