# カタログフィード 構造化された商品データと在庫データを Stripe と共有すると、AI エージェントが見つけられるようになります。 製品および在庫フィード仕様を使用して、構造化された製品および在庫データを Stripe と共有し、カタログを AI エージェントに配信して検索やショッピングに活用できます。まずは完全な製品フィードを送信し、その後、増分在庫フィードの更新を行って、在庫レベルと入手可能性を常に最新の状態に保ちます。 ## 製品フィードの仕様 製品フィード仕様を使用して、構造化された製品データ全体 (タイトル、説明、識別子、価格設定、フルフィルメント、メディアなど) を提供します。各行は製品またはバリエーションを表します。 1. このドキュメントのフィールド参照情報を使用して商品データをフォーマットします。各フィールドには、サンプル値、検証ルール、および必須、推奨、オプションのいずれかが含まれます。 1. [Stripe 商品カタログインポート API](https://docs.stripe.com/api/v2/commerce/product-catalog-imports.md) を使用して、商品データを CSV 形式で安全に送信します。各行は 1 つの商品またはバリアントを表します。本番環境にプッシュする前に、初回の完全なフィードをサンドボックスエンドポイントに送信し、データが正しく解析され、すべてのフィールド要件を満たしていることを確認します。 1. データを最新の状態に保ち、フィードを頻繁に更新してください。商品属性、価格、フルフィルメントの詳細に変更があった場合は、すぐに更新し、顧客の信頼を維持するとともに、古いリストへの掲載を防ぎます。Stripe はお客様のデータを検証してクリーンアップし、Stripe 商品フィードにインデックスを作成し、各エージェントが必要とする形式に変換します。 ### フィード処理モード 商品フィードのアップロードは、`アップサート`(デフォルト) と`置換`の 2 つの処理モードに対応しています。 アップサートモードでは、各行を、`id` で識別される商品の挿入または更新として扱います。 - `ID` が存在しない場合は、商品が作成されます。 - `id` がすでに存在する場合は、その行で指定された値で製品が更新されます。 - ファイルに含まれていない商品は変更されません。 置換モードでは、アップロードされたファイルが完全な正規の商品カタログとして扱われます。 - `ID` が存在しない場合は、商品が作成されます。 - `id` がすでに存在する場合は、その行で指定された値で製品が更新されます。 - お客様のカタログには存在するものの、アップロードされたファイルには含まれていない商品は完全に削除されます。 - 置換モードに対応しているのは、商品フィードのみです。 アップロードしたファイルでカタログ全体を定義する場合は、置換モードを使用します。含めていない商品に影響を与えずに部分的な更新を適用する場合は、アップサートモードを使用します。 ### 削除の動作 フィードを使用して商品またはバリアントを削除するには、CSV にオプションの `delete` 列を含めます。削除する商品は `true` に設定します。保持する商品については、`false` に設定するか、このフィールドを空白のままにします。 `delete=true` の場合、Stripe はその行の `id` 列と `delete` 列のみを読み取り、その他すべての列を無視します。 ### ディスカバリー専用プロダクト `disable_checkout=true` の商品は検出のために AI エージェントにシンジケートされますが、エージェント内での決済の対象にはなりません。エージェントが検出専用の商品を表示すると、ユーザーは商品の `link` URL にリダイレクトされ、お客様のウェブサイトでの購入を完了します。 検出専用の製品は、他の製品と同じフィード処理ルールに従います。エージェントは、インデックス作成、検索、ランク付けを行うことができます。唯一の違いは、購入アクションがエージェント内の決済セッションを開始するのではなく、お客様のサイトにリダイレクトされることです。 このフィールドの設定方法については、[フィード処理の手順](https://docs.stripe.com/agentic-commerce/product-feed.md#feed-processing-instructions)をご覧ください。 ## 商品フィードフィールドリファレンス 以降のセクションで、Stripe 製品フィードで使用されるスキーマ全体をレビューします。各テーブルには、データ型、例、要件が記載されています。 ### 基本的な商品データ 各商品を一意に定義する必須の識別子と説明文を指定します。 | フィールド | データタイプ | 要件 | | ----------- | ------------------------------ | -- | | id | String (英数字) 最大 100 文字 | 必須 | 商品の一意の識別子。可能であれば商品の SKU を使用し、データを更新する際にも同じ ID を維持してください。**例: SKU12AB3456** | | title | String (UTF-8 テキスト) 最大 150 文字 | 必須 | 商品の名称。商品を正確に説明し、ランディングページのタイトルと一致するものにしてください。すべて大文字にはしないでください。**例: 男性用花柄ポロシャツ** | | description | String (UTF-8 テキスト) 最大 5000 文字 | 必須 | 商品の説明。商品情報のみを記載してください。自社ストアへのリンクやセールス情報、他社商品、関連アクセサリーなどについての詳細は記載しないでください。プレーンテキストのみ使用できます。**例: この男性用花柄ポロシャツでゴルフの時間がもっと華やかに、楽しくなります** | | link | URL (RFC 1738) | 必須 | 商品のランディングページ。認証済みのドメイン名を使用し、`https` (推奨) または `http` で始めます。`HTTP 200` で解決する必要があります (リンク切れ不可)。**例: https://example.com/product/SKU12AB3456** | ### 製品 ID 世界中で認知されているこれらの識別子を使用して、検索や照合において商品を差別化します。 | フィールド | データタイプ | 要件 | | ----- | ---------------------------- | ----------------------- | | brand | 文字列 | 映画、書籍、音楽録音ブランドを除くすべてに必須 | 商品のブランド名。一般に顧客が認識するその商品のブランド名を記載してください。最大 70 文字。**例: Stripe** | | gtin | String (数値形式の GTIN、UPC、ISBN) | 推奨 | 商品の国際標準商品識別コード (GTIN)。最大 50 文字。ダッシュやスペースは入れないでください。**例: 3234567890126** | | mpn | String (英数字) | GTIN がない場合は必須です | 商品の製造者部品番号 (MPN)。製造者によって割り当てられた MPNのみ入力して下さい。最大 70 文字。**例: STR12345** | ### メディア 商品を正確に表現するために、ビジュアルメディアとオプションのリッチメディアを提供します。 | フィールド | データタイプ | 要件 | | --------------------- | ----------------- | -- | | image_link | URL (RFC 1738) | 必須 | 商品のメイン画像の URL。JPEG または PNG 形式を使用してください。`http` または `https` で始めます (`https` 推奨)。一般公開されている必要があります。推奨最小サイズ: 800 × 800 px。透かし文字、テキストのオーバーレイ、プロモーション用グラフィックは使用しないでください。**例: https://example.com/image1.jpg** | | additional_image_link | URL 配列 (RFC 1738) | 任意 | 商品の追加の画像の URL。要件は `image_link` の場合と同じです。最大 10 枚の画像がサポートされます。様々な角度からの画像、パッケージ、または使用シーンの画像を使用してください。 - 1 つの画像を送信するには、(エンコードされた) URL を送信します: **https://www.example.com/image2.jpg**. - 1 枚以上の画像を使用する場合 (最大 10 枚)、各画像の URL はコンマで区切ってください (例: **https://www.example.com/image2.jpg,https://www.example.com/image3.jpg**)。URL自体に含まれるコンマは、エンコード (`%2C` に置換) してください。ただし、複数の画像 URL を区切るためのコンマはエンコードしないでください。**https://www.example.com/image2%2C3.jpg,https://www.example.com/image2%2C4.jpg**.**Example: https://example.com/image2.jpg,…** | | video_link | URL (RFC 1738) | 任意 | 使用中または開封時の様子を映した商品ビデオ。一般公開されている必要があります (例: YouTube、Vimeo または MP4 への直接リンク)。推奨形式: MP4、MOV、 WebM。推奨時間: 15 ～ 60 秒。商品に関連する音声のみを入れてください (例: サウンドデモ)。映像にはメイン画像と同じ商品を使用してください。**例: https://youtu.be/12345** | | model_3d_link | URL (RFC 1738) | 任意 | 商品の 3D モデルを表示する追加リンク。推奨形式: GLB または GLTF。一般公開されている必要があります。読み込み速度を最適化するためにファイルサイズは 20MB 未満にしてください。3D モデルが商品の形や色を正確に再現するようにしてください。**例: https://www.example.com/products/xyz.glb** | ### 項目情報 正確なフィルタリングと分類の配置のために、物理的特性と分類を説明します。 | フィールド | データタイプ | 要件 | | ----------------------- | ------------------------------------------------------------------ | ------------------------------------ | | condition | Enum (`new`, `refurbished`, `used`) | 商品の状態が新品と異なる場合は必須 | 販売時の商品の状態。 - `新品`: 元の未開封の梱包に入った新品。 - `再生品`: 専門家によって動作可能な状態に修復され、保証付きで、元の梱包材が欠落している場合があります。 - `中古品`:以前使用されたもので、元のパッケージが開封されているか、紛失しているもの。**例: 新品** | | google_product_category | Google 商品分類に基づく StringValue。数字で表されるカテゴリ ID またはそのカテゴリのフルパスを入力して下さい。 | 推奨 | 事前に定義された Google 商品分類。最も関連性の高いカテゴリのみを記載してください。カテゴリのフルパス、または数値のカテゴリ IDのいずれかを記載してください。両方記載することはできません。可能であればカテゴリ ID の方を使用します。**例: 2271** または **ファッション・アクセサリー > 衣料品 > ドレス** | | product_category | String (カテゴリー分類) | `google_product_category` がない場合は必須です | 商品を定義する商品カテゴリ。`>` で区切ってください。カテゴリの全階層を記載してください。ダッシュやスペースは入れないでください。**例: ファッション・アクセサリー > 衣料品 > アウターウェア** | | age_group | Enum (`newborn`, `infant`, `toddler`, `kids`, `adult`) | 任意 | 商品が対象とする人口統計。 - `新生児`: 0 ~ 3 カ月。 - `幼児`: 生後 3 ～ 12 ヶ月。 - `幼児`: 1 ～ 5 歳。 - `子供`: 5 ～ 13歳。 - `adult`: 中学生以上。**例: 乳児** | | material | 文字列 | 一連のバリアントで異なる商品を区別する場合に必要です | 商品の主要な生地または素材。最大 100 文字。**例: 皮革** | | length | 数字と単位 (`cm` および `in`) | 任意 | 商品の長さ。各寸法の属性 (`length`、`width`、`height`) にはすべて同じ単位を使用してください。数値は小数点を含むことができます。**例: 20 in** | | width | 数字と単位 (`cm` および `in`) | 任意 | 商品の幅。各寸法の属性 (`length`、`width`、`height`) にはすべて同じ単位を使用してください。数値は小数点を含むことができます。**例: 20 in** | | height | 数字と単位 (`cm` および `in`) | 任意 | 商品の高さ。各寸法の属性 (`length`、`width`、`height`) にはすべて同じ単位を使用してください。数値は小数点を含むことができます。**例: 20 in** | | weight | 数字と単位 (`lb`、`oz`、`g`、`kg`) | 任意 | 商品の重量。この属性には実際に組み立てられた商品の重量を記載してください。数値は小数点を含むことができます。**例: 2.5 lb** | ### バリアント 色やサイズなどのバリアントの関係を定義し、関連する SKU が 1 つの親の下にグループ化されるようにします。バリアントを送信する場合は、すべてのバリアントに同じ `item_group_id` を含めます。 | フィールド | データタイプ | 要件 | | ---------------- | --------------------------------- | ----------------- | | item_group_id | 文字列 | バリアントが存在する場合は必須です | 複数のバリエーションがある商品のグループ ID。各バリエーショングループに対して、一意の値を使用してください。可能であれば親 SKU を使用してください。商品データを更新する際にも同じ値を維持してください。最大 70 文字。同じ `item_group_id` を共有するすべての商品に対して、同じバリエーション属性のセットを使用してください。例えば、あるドレスに 2 種類の色とサイズがある場合、各バリエーションに色とサイズ双方の値を含める必要があります。**例: Shoe1234** | | item_group_title | String (UTF-8 テキスト) | 任意 | 商品グループの名称。関連するバリエーショングループを表す、明瞭でわかりやすい名前を使用してください (例: “男性用ランニングシューズ”)。最大 150 文字。**例: シューズ** | | color | 文字列 | 推奨 (アパレル) | 商品の色。複数の色がある商品の場合には、メインカラーを記載してください。推奨される文字数: 40 文字以内。最大 100 文字。**例: 黒** | | size | 文字列 | 推奨 (アパレル) | 商品のサイズ。最大 20 文字。**例: 10** | | size_system | 国コード (ISO 3166) | 推奨 (アパレル) | サイズ規格。2 文字の国コード。**例: US** | | gender | Enum (`male`, `female`, `unisex`) | 推奨 (アパレル) | 商品の対象性別。**例: 男性** | ### カスタムバリアントオプション 名前と値のペアを使用して、バリエーションセクションにまだ含まれていない商品バリアントの標準以外の特性を定義します (「Material/Oak」や「Pattern/Floral」など)。 | フィールド | データタイプ | 要件 | | --------------------------------- | ------------------- | -- | | custom_variant_option_name_{1-3} | String (UTF-8 テキスト) | 任意 | カスタム商品バリアントオプションを最大 3 つ定義します。CSV の各列に 1 ~ 3 の番号を付けます。`custom_variant_option_name_1`、`custom_variant_option_name_2`、`custom_variant_option_name_3` です。各バリアントオプション名は、同じ番号の値にマッピングされます。たとえば、`custom_variant_option_name_1` は `custom_variant_option_value_1` にマッピングされます。**例: Material** | | custom_variant_option_value_{1-3} | String (UTF-8 テキスト) | 任意 | カスタム商品バリアントの値を、カスタムバリアントオプション名で定義されたバリアントに設定します。CSV の各列に 1 ~ 3 の番号を付けます。`custom_variant_option_value_1`、`custom_variant_option_value_2`、`custom_variant_option_value_3` です。各バリアントオプション値は、同じ番号の名前にマッピングされます。たとえば、`custom_variant_option_value_1` は `custom_variant_option_name_1` の値です。**例: Oak** | ### 可用性と在庫 リアルタイムの在庫状況と数量を提供して、購入の正確性を維持します。 | フィールド | データタイプ | 要件 | | --------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------- | | availability | Enum (`in_stock`, `out_of_stock`, `preorder`, `backorder`) | すべての商品に必須 | 商品の入手可能性。**例: in\_stock (在庫あり)** | | availability_date | 日付 (ISO 8601) | 商品の在庫が `preorder` に設定されている場合は必須です | 予約商品が配達可能になる日付。**例: 2026-02-24** | | expiration_date | 日付 (ISO 8601) | 任意 | 商品が表示されなくなる日付。**例: 2026-12-31** | | inventory_not_tracked | Boolean (`true` or `false`) | 任意 | 商品の在庫を追跡するかどうかを指定します。 - `true`: 在庫は追跡されません(例: デジタル商品、オーダーメイド商品)。 - `inventory_quantity` は必ず空欄になります。 - `false`: 在庫は追跡され、`inventory_quantity` が必須になります。**例: false** | | inventory_quantity | Integer (非負整数) | `inventory_not_tracked` が `false` の場合は必須です。`true` の場合は空白のままにします。 | このアイテムの販売可能なユニット。`inventory_not_tracked` が `true` の場合は空欄にしてください。**例: 100** | ### 価格とプロモーション 表示とプロモーションロジックの料金情報を指定します。 | フィールド | データタイプ | 要件 | | ------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | price | 数値と通貨コード (ISO 4217) | すべての商品に必須 | 商品の価格。**例: 15.00 USD** | | sale_price | 数値と通貨コード (ISO 4217) | 任意 | 割引価格。**例: 12.99 USD** | | sale_price_effective_date | 日付 (ISO 8601) | `sale_price` を指定した場合は必須 | セール期間。開始日と終了日を `/` で区切ってください。**例:2025-12-01/2025-12-15** | | stripe_product_tax_code | String (Stripe 商品税コード (PTC)) | 税金計算に Stripe Tax を使用する場合に必要 | 税計算のために Stripe 商品税コードを使用して商品を分類してください。このコードを指定することで、Stripe が商品のタイプと管轄区域に基づいて正しい税率を適用できるようになります。**例: txcd\_99999999** | | third_party_tax_code | 文字列 `provider:tax_code` サポートされているプロバイダー: `anrok` 最大 120 文字 | 任意。`stripe_product_tax_code` が指定されておらず、税計算に [Anrok](https://www.anrok.com) を使用する場合は必須です。 | [Anrok](https://www.anrok.com) で税計算する際に商品を分類するためのフィールドです。値は、プロバイダー名を小文字にした`: ` の形式で指定してください。エージェンティックコマースで現在サポートされているプロバイダーは `anrok` のみです。Anrok 用に商品を分類する場合は、`stripe_product_tax_code` の代わりにこのフィールドを使用してください。**例: anrok:prod\_abc123** | | tax_behavior | Enum (`inclusive` or `exclusive`) | 任意 | 商品価格が税込み (内税) か税抜き (外税) かを指定します。このフィールドを省略すると、デフォルト値は `exclusive` になります。**例: 外税** | | applicable_fees | String`country:region:fee_label:fee_amount [:fee_basis]`: 各オプションをコロン区切りの値として入力し、複数のエントリはコンマで区切ります。 | オプション (規制または地域の手数料が適用される場合は必須) | 商品タイプと地域に応じて適用される手数料と追加料金を指定するフィールドです。これらの手数料は基本商品価格には含まれません。決済時およびレポート時で個別の明細項目として使用してください。各手数料はコロン区切りの値として入力します: - `country` (必須):ISO 3166-1 alpha-2 国コード (US、DE など)。 - `region` (必須): 地域、州、準州、または都道府県 (CA など)。指定した国内のすべての地域または州に適用するには、`ALL` を使用します。 - `fee_label` (必須): 手数料の判読可能な名前 (リサイクル手数料、ボトル入金、エコ決済など)。名前にコロンを使用しないでください。 - `fee_amount` (必須): 小数点区切り文字としてピリオドを使用し、ISO 4217 通貨コードを付けた固定手数料金額 (例: 5.00 USD)。 - `fee_basis` (任意): 複数の商品が購入された場合の手数料の適用方法を指定します。使用できる値は `per_item` (単品ごとに手数料を請求) と `per_order` (注文ごとに 1 回手数料を請求) です。このフィールドを省略した場合、デフォルト値は `per_item` になります。**例: US:CA:リサイクル料金:0.25 USD、DE:全域:ボトル預託金:0.10 EUR、US:CO:小売配送手数料:0.29 USD:per\_order** | ### フルフィルメント 配送オプション、料金、配送予定日を指定します。 | フィールド | データタイプ | 要件 | | ----------------------- | -------------------------------------------------------------------------------------------------------- | --------------------- | | shipping | String`country:delivery_area:service:speed_range:price`: 各オプションにはコロンで区切った値を入力し、複数の項目がある場合にはコンマで区切ってください。 | 商品が配送可能な場合 (物品など) に必要 | 商品の配送料、配送にかかる時間、配送先。各オプションは、コロンで区切った値の形式で入力してください。 - `country` (必須):商品の配送先となる国を示す ISO 3166-1 alpha-2 の国コードを指定します (アメリカ、DE など)。 - `delivery_area` (必須): 商品の配送先を定義する次のいずれかの値: - `region`:ISO 3166-2 サブディビジョンコードを使用し、国名を付加しない地域、州、都道府県は (`VA`、`NY`など) のように書きます。そのルールを国のすべての地域・州・県に適用する場合は、`ALL` と指定します。 - `postal_code`: 郵便番号または郵便番号の範囲 (現在はアメリカのみ対応)。使用できる形式: - シングルコード: `94012` - 範囲: `73114-74547` - 末尾のワイルドカード: `94*` - 複数のワイルドカード範囲: `94* - 95*` - `service` (必須): サービスの判読可能な名前 (Standard や Express の配送など)。 - `speed_range` (オプション): 配送に必要な最小日数と最大日数 (例: `3 ～ 5 日`)。 - `price` (必須): 固定の配送料。小数点はピリオドを使用し、ISO 4217 通貨コードを付します (例: `3.00 USD`)。**例 (地域): US:ALL:Standard Shipping:3-5:0.00 USD,US:ALL:Expedited Shipping:1-2:12.99 USD\****例 (郵便番号): US:94012:Standard Shipping:3-5:0.00 USD,US:73114-74547:Expedited Shipping:1-2:9.99 USD,US:94*:Expedited Shipping:1-2:9.99 USD,US:94*-95*:Standard Shipping:2-5:0.00 USD** | | shipping_cost_basis | Enum (`per_order`, `per_item`) | 任意 | 顧客が同じ SKU を複数単位購入した場合に `shipping` フィールドにおける配送料の定義の仕方を指定します。この設定を省略すると、デフォルトの挙動は `per_order` になります。 - `per_order`: 数量にかかわらず、該当する配送サービスに対して注文ごとに送料を 1 回請求します。 - `per_item`: この SKU の単位当たりの配送料を請求してください (つまり購入数量を掛けた値になります)。**例: per\_item** | | shipping_tax_behavior | Enum (`inclusive`、`exclusive`) | 任意 | 送料に適用税が含まれているかどうかを指定します。このフィールドを省略した場合、デフォルト値は商品の `tax_behavior` になります。**例: exclusive** | | free_shipping_threshold | String`country:region:service:price_threshold`: 各オプションにはコロンで区切った値を入力し、複数の項目がある場合にはコンマで区切ってください。 | 任意 | 注文レベルの送料無料ルールを定義します。注文商品の小計が指定の基準額以上の場合、該当する配送サービスの配送料が `0.00` になります。各配送料オプションは、コロンで区切った値の形式で入力してください。 - `country` (必須):商品の配送先となる国を示す ISO 3166-1 alpha-2 の国コードを指定します (アメリカ、DE など)。 - `region` (必須): ISO 3166-2 の下位区分コードを使用し、国プレフィックスを付けない地域、州、準州、都道府県 (VA や NY など)。指定した国内のすべての地域または都道府県に適用するには、`ALL` を使用します。 - `service` (必須): 配送サービス名。`shipping`欄で定義されたサービス (標準配送や Express 配送など) に一致している必要があります。 - `price_threshold` (必須): 各明細項目の割引後、税引き前、および送料を除いた注文商品の小計。金額と通貨コードで表記。小数点はピリオドを使用し、ISO 4217 通貨コードを付します (例: `50.00 USD`)。**例: US:ALL:Standard Shipping:50.00 USD,US:ALL:Expedited Shipping:100.00 USD** | | shipping_exclusions | String`country:delivery_area:service`: 各除外はコロン区切りの値として指定し、複数のエントリはカンマで区切ります。 | 任意 | この商品を配送できない場所を定義します。このフィールドを使用して、1 つの国の中で特定の地域または郵便番号への配送を制限できます。各除外は次のコロン区切りの値として指定します: - `country` (必須): 商品を配送できない国を示す ISO 3166-1 alpha-2 の国コードです (例: US または DE)。 - `delivery_area` (必須): 商品を配送できない場所を定義する、以下のいずれかの値です: - `region`: 国プレフィックスを含まない ISO 3166-2 の行政区分コードで指定する地域、州、準州、または都道府県です (例: `AK` または `HI`)。国全体を除外するには `ALL` を使用します。 - `postal_code`: 郵便番号または郵便番号の範囲 (現在はアメリカのみ対応)。使用できる形式: - 単一コード: `96701` - 範囲: `96701-96898` - 末尾のワイルドカード: `967*` - 複数のワイルドカード範囲: `967*-968*` - `service` (任意): 除外する配送サービス名です。`shipping` フィールドで定義されたサービスと一致する必要があります。これを省略すると、除外はすべての配送サービスに適用されます。**例: US:AK:Standard Shipping,US:HI:Standard Shipping,US:96701-96898:Expedited Shipping** | ### パフォーマンスとレビューシグナル パフォーマンスとレビューのシグナルを共有して、AI エージェントとランキングシステムが高品質で信頼できる製品を識別できるようにします。 - これらのフィールドはオプションですが、推奨されます。これらにより、エージェントインターフェイス全体での発見性、ランキング、パーソナライゼーションが向上します。 - 集計された指標のみを提供し、ユーザーレベルのデータや個人を特定できる情報は除外します。 - これらの指標を定期的に (毎週など) 更新して、正確性を維持します。 | フィールド | データタイプ | 要件 | | --------------------- | -------------------- | ------------------------------------- | | popularity_score | 数値 (0–5 段階) | 推奨 | 該当商品またはバリエーションの総合的な人気指標。カタログ全体で一貫して 0 から 5 のスケールを使用してください (0 が最低、5 が最高)。この値は閲覧数、カート追加イベント、成約、売上順位などのシグナルから導き出せます。この値を最新状態に保つため、一貫した集計期間 (例: 過去 90 日間) を使用して値を更新してください。**例: 4.7** | | return_rate | 数値 0–100 (`%` 記号は除く) | 推奨 | 該当商品またはバリエーションの返品数の割合。0 ～ 100 の数値で表されます (例: 2% の場合は `2.0` と表記)。一貫した集計期間 (例: 過去 90 日間) を使用してください。**例: 2.0** | | product_review_count | Integer (非負整数) | 推奨 | 該当商品またはバリエーションに対するレビュー総数。`product_review_rating` の計算に使用する母集団と一致させてください。レビューが 1 件もない場合は `0` を記入してください。**例: 124** | | product_review_rating | 数値 (1–5 段階) | `product_review_count` が 0 より大きい場合は必須 | この商品またはバリエーションに対するレビューの平均評価。フィード全体で一貫して 1 から 5 のスケールを使用してください (1 が最低、5 が最高)。この値は `product_review_count` と同じデータセットに基づいている必要があります。`product_review_count` が `0` の場合にはこのフィールドを空欄にしてください。**例: 4.3** | ### 製品関係 アップセル、クロスセル、関連商品など、検出と推奨のための関連商品を指定します。 | フィールド | データタイプ | 要件 | | ---------------- | ---------------------------------------------------------------------------- | -- | | related_products | String`relationship_type:target_id`: 各オプションをコロン区切りの値として入れ、複数のエントリはカンマで区切ります。 | 任意 | この項目の商品関連付けを定義します。各関係をコロン区切りの値としてフォーマットします。 - `relationship_type` (必須): `upsell`、`cross_sell`、`substitute`、または `accessory` のいずれかである必要があります。 - `target_id` (必須): 商品の一意の識別子。ターゲットが、取得された商品フィードデータの既存の `ID` と一致しない場合、エージェントに同期する前に関係を削除します。 - 自己参照なし: `target_id` を現在の商品と同じにすることはできません。 - この行に重複する `target_id` 値はありません: 複数の関係タイプを指定することはできません (たとえば、この商品から同じターゲット商品への `upsell` と `cross_sell` の両方を 1 行に指定することはできません)。 - 商品行ごとに最大 10 件の商品関係。**例: upsell:SKU12AB3457,cross\_sell:SKU12AB3458,accessory:SKU12AB3459** | ### コンプライアンス 規制に関する警告、免責事項、年齢制限を含めます。これらのフィールドは、法律上の義務を果たし、消費者を保護するのに役立ちます。 | フィールド | データタイプ | 要件 | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | product_warning | String`type:message`:各オプションをコロンで区切り、複数のエントリーはカンマで区切ります。サポートされるタイプ: `legal_disclaimer`、`safety_warning`、`prop_65` 1 メッセージあたり最大 1,000 文字 | 任意 (規制または法務上の警告が適用される場合は必須) | この製品またはバリアントに適用される警告を 1 点以上指定します。このフィールドは、規制に基づく警告要件 (California Proposition 65 など) が課される項目の場合には入力が必須です。製品の警告要件を含め、適用されるすべての法令遵守の責任を負います。これらの警告は、お客様が指定すると、エージェントの決済画面に表示されます。各警告の形式はコロン区切りの値です。 - `type` (必須): 警告のタイプ。サポートされる値: `legal_disclaimer`、`safety_warning`、`prop_65`。 - `message` (必須): ユーザーに表示される警告テキスト。**例: prop\_65: この製品を使用すると、鉛を含む化学物質に曝される可能性があります。** | | age_restriction | Integer (非負整数) | 任意 | この商品を購入できる最低年齢。**例: 21** | ### カスタムラベル カスタムラベルを使用すると、セグメンテーション、フィルタリング、後続の連携のために商品にタグを付けてグループ化できます。これらのフィールドはエンドユーザーには表示されず、商品の表示、価格設定、フルフィルメントには影響しません。 | フィールド | データタイプ | 要件 | | ------------------ | -------------------------- | -- | | custom_label_{0-4} | 文字列 (UTF-8 テキスト) 最大 100 文字 | 任意 | 内部目的にのみ、最大 5 つのカスタムラベルを使用できます。各フィールドには 1 つの文字列値を指定できます。対応しているフィールドは `custom_label_0`、`custom_label_1`、`custom_label_2`、`custom_label_3`、`custom_label_4` です。価格、在庫状況、ブランドなど、すでに他のフィールドでカバーされている構造化された商品属性を、これらのフィールドでエンコードしないでください。**例: 季節** | ### フィード処理手順 システムがフィードの各行を処理する方法を制御する操作フィールドを定義します。 | フィールド | データタイプ | 要件 | | ---------------- | --------------------------- | -- | | delete | Boolean (`true` or `false`) | 任意 | 恒久的に削除する商品またはバリエーションに削除マークを付けてください。`true` に設定すると、`id` で特定された商品を削除し、その行の他のすべての項目は無視されます。省略された場合、または `false` の場合、その行は *upsert* (A combined operation that updates an existing record if it exists or inserts it if it doesn’t) として処理されます。**例: true** | | disable_checkout | Boolean (`true` or `false`) | 任意 | この商品をエージェント内の決済フローから除外します。`true` の場合、商品は検出のために AI エージェントにシンジケートされますが、エージェントはエージェント内の決済セッションを開始する代わりに、ユーザーを商品の `link` URL に誘導して購入を完了させます。このフィールドを省略するか、`false` に設定すると、ビジネスで決済の設定が完了している場合、決済は引き続き有効になります。**例: true** | サンプルファイルを[ダウンロード](https://files.stripe.com/files/MDB8YWNjdF8xTXFRbnFKN2NxSnkwUTVifGZfbGl2ZV9hT0VDaWprbDBkakFNeXRzYW5oVzhyOFY00skGbF2tU)します。 ## 在庫フィード仕様を使用します 在庫フィードを使用して、製品フィード全体を再提出することなく、商品の在庫状況と在庫数量を更新します。倉庫、POS、フルフィルメントシステムから頻繁に更新を送信して、エージェントインターフェイス全体で正確な在庫ステータスを商品に反映します。 1. **製品フィードの同期を維持する**: インベントリファイルの `id` 値は、メインの製品フィードにすでに存在している必要があります。 1. **在庫ファイルを頻繁に送信**: [Stripe 商品カタログインポート API](https://docs.stripe.com/api/v2/commerce/product-catalog-imports.md) を使用して、CSV 形式で更新を送信します。 1. **部分的な更新を送信**: 変更された SKU のみを含めます。含まれていない SKU は、最新の既知の在庫状態を保持します。 ## 在庫フィードフィールドの参照 以下のリファレンスを使用して、在庫フィードフィールドの形式を設定します。 ### 在庫フィードのフィールド リアルタイムの在庫状況と数量を提供して、購入の正確性を維持します。 | フィールド | データタイプ | 要件 | | ------------------ | ---------------------------------------------------------- | --------------------------------- | | id | String (英数字) | 必須 | 主要な商品フィードにある `id` と一致させてください。この値がシステム上のキー識別子になります。**例: SKU12AB3456** | | availability | Enum (`in_stock`, `out_of_stock`, `preorder`, `backorder`) | すべての商品に必須 | 商品の入手可能性。**例: in\_stock (在庫あり)** | | availability_date | 日付 (ISO 8601) | 商品の在庫が `preorder` に設定されている場合は必須です | 予約商品が配達可能になる日付。**例: 2026-02-24** | | inventory_quantity | Integer (非負整数) | すべての商品に必須 | 販売可能な単位。**例: 100** | ## 価格フィード仕様を使用する 価格フィードを使用して、商品フィード全体を再提出することなく、表示とプロモーションの価格情報を更新できます。 1. **製品フィードの同期を維持する**: 価格ファイルの `id` 値は、メインの製品フィードにすでに存在している必要があります。 1. **価格ファイルを頻繁に送信**: [Stripe 商品カタログインポート API](https://docs.stripe.com/api/v2/commerce/product-catalog-imports.md) を使用して、CSV 形式で更新を送信します。 1. **部分的な更新を送信** : 変更された SKU のみを含めます。含まれていない SKU は、最新の既知の価格情報を保持します。 ## 価格フィードフィールドの参照 以下の参照情報を使用して、価格フィードフィールドの形式を設定します。 ### 価格フィードのフィールド 表示とプロモーションロジックの料金情報を指定します。 | フィールド | データタイプ | 要件 | | ------------------------- | ------------------- | ----------------------- | | id | String (英数字) | 必須 | 主要な商品フィードにある `id` と一致させてください。この値がシステム上のキー識別子になります。**例: SKU12AB3456** | | price | 数値と通貨コード (ISO 4217) | すべての商品に必須 | 商品の価格。**例: 15.00 USD** | | sale_price | 数値と通貨コード (ISO 4217) | 任意 | 割引価格。**例: 12.99 USD** | | sale_price_effective_date | 日付 (ISO 8601) | `sale_price` を指定した場合は必須 | セール期間。開始日と終了日を `/` で区切ってください。**例:2025-12-01/2025-12-15** | ## プロモーションフィードの仕様を使用する プロモーションフィードを使用して、実施中および実施予定のプロモーション (割引コード、割引率、固定割引額、送料無料オファーなど) を提供します。各行は 1 つのプロモーションを表します。プロモーションフィードは商品フィードと連携して機能し、カタログ内の `id` または `item_group_id` で商品を参照します。 1. **商品フィードとの同期を維持する**: プロモーションファイル内の商品 ID およびアイテムグループ ID は、メイン商品フィードの `id` または `item_group_id` の値と一致する必要があります。 1. **プロモーションファイルを頻繁に送信する**: [Stripe Product Catalog Import API](https://docs.stripe.com/api/v2/commerce/product-catalog-imports.md) を通じて CSV 形式で更新を送信します。 1. **差分更新を送信する**: 変更されたプロモーションのみを含めます。プロモーションを省略した場合、最後に設定されたプロモーション情報が保持されます。 ## プロモーションフィードフィールドのリファレンス 次のリファレンスを使用して、プロモーションフィードフィールドをフォーマットします。 ### 基本的なプロモーションデータ 各プロモーションを定義する必須の識別子と日付を指定します。 | フィールド | データタイプ | 要件 | | ------------- | ----------------------------- | -- | | promotion_id | String (英数字) 最大 100 文字 | 必須 | プロモーションの一意の識別子。データを更新する際は ID を同じに保ちます。**例: PROMO\_SPRING2026** | | title | String (UTF-8 テキスト) 最大 150 文字 | 必須 | 人間が読める形式のプロモーションタイトル。決済時に顧客に表示される場合があります。**例: Spring Sale - 20% Off** | | link | URL (RFC 1738) | 任意 | プロモーションのランディングページ URL。`http` または `https` (`https`推奨) で始める必要があります。`HTTP 200` を返す必要があります (リンク切れ不可)。**例: https://example.com/promo** | | active_period | DateTime (ISO 8601) | 必須 | プロモーションの開始日と終了日。開始日と終了日は `/` で区切ります。両方の値は、時刻とタイムゾーンを含む完全な ISO 8601 タイムスタンプである必要があります (UTC 推奨)。**例: 2026-05-01T00:00:00Z/2026-12-15T23:59:59Z** | ### 割引の設定 プロモーションが提供する割引の種類と値を指定します。 | フィールド | データタイプ | 要件 | | -------------------- | ------------------------------------------------- | ------------------------------------- | | benefit_type | Enum (`percent_off`、`amount_off`、`free_shipping`) | 必須 | このプロモーションが提供する割引の種類。 - `percent_off`: プロモーションで割引率を適用します。`percent_off` フィールドに割引率を含めます。 - `amount_off`: プロモーションで固定割引額を適用します。`amount_off` フィールドに割引額を含めます。 - `free_shipping`: プロモーションで送料無料を適用します。`promotion_code` フィールドに有効な引き換えコードを含めます。**例: percent\_off** | | percent_off | 整数 (0–100) | `benefit_type` が `percent_off` の場合に必須 | プロモーションで適用される割引率。**例: 20** | | amount_off | 数値と通貨コード (ISO 4217) | `benefit_type` が `amount_off` の場合に必須 | プロモーションで適用される固定割引額。**例: 10.00 USD** | | minimum_order_amount | 数値と通貨コード (ISO 4217) | 任意 | プロモーションを適用するために必要な最低注文小計。小計は税金、送料、割引の前に計算されます。すべてのプロモーションタイプに適用されます。**例: 50.00 USD** | ### 商品のターゲット設定 プロモーションを適用する商品を指定します。 | フィールド | データタイプ | 要件 | | ----------------------- | ----------------------------------------- | ---------------------------------------------------- | | target_selection | Enum (`all_products`、`specific_products`) | 必須 | プロモーションをすべての商品に適用するか、特定の商品のみに適用するかを指定します。 - `all_products`: プロモーションがカタログ内のすべての商品に適用されます。`target_ids`、`target_item_group_ids`、`excluded_ids`、`excluded_item_group_ids` は空のままにします。 - `specific_products`: プロモーションが商品のサブセットに適用されます。`target_ids`、`target_item_group_ids`、`excluded_ids`、`excluded_item_group_ids` のうち少なくとも 1 つを指定します。`target_ids` と `target_item_group_ids` で対象セットを定義し、`excluded_ids` と `excluded_item_group_ids` でそのセットから商品を除外します。**例: all\_products** | | target_ids | 文字列 (カンマ区切りの商品 SKU) | `target_selection` が `specific_products` の場合に条件付きで必須 | プロモーションを特定の商品 SKU に限定します。値は商品フィードの `id` 属性と一致する必要があります。**例: SKU123,SKU456** | | target_item_group_ids | 文字列 (カンマ区切りのアイテムグループ ID) | `target_selection` が `specific_products` の場合に条件付きで必須 | プロモーションを特定のアイテムグループに限定します。グループ内のすべてのバリアントが対象となります。値は商品フィードの `item_group_id` 属性と一致する必要があります。**例: POLO123** | | excluded_ids | 文字列 (カンマ区切りの商品 SKU) | `target_selection` が `specific_products` の場合に条件付きで必須 | 対象選定ロジックが適用された後に、特定の商品 SKU をプロモーションから除外します。値は商品フィードの `id` 属性と一致する必要があります。商品が `target_ids` と `excluded_ids` の両方に含まれる場合、除外されます。**例: SKU222,SKU333** | | excluded_item_group_ids | 文字列 (カンマ区切りのアイテムグループ ID) | `target_selection` が `specific_products` の場合に条件付きで必須 | 対象選定ロジックが適用された後に、特定のアイテムグループをプロモーションから除外します。値は商品フィードの `item_group_id` 属性と一致する必要があります。アイテムグループが `target_item_group_ids` と `excluded_item_group_ids` の両方に含まれる場合、除外されます。**例: POLO456** | ### 引き換え 顧客がプロモーションを引き換える方法を設定します。 | フィールド | データタイプ | 要件 | | ---------------- | ------------------------------------------------------------------- | -------------------------------------------- | | application_type | Enum (`automatic`、`promotion_code`) | 必須 | オファーを引き換えるためにプロモーションコードが必要かどうかを示します。 - `automatic`: 注文が条件を満たす場合、オファーは決済時に自動的に適用されます。 - `promotion_code`: 顧客が決済時にプロモーションコードを入力するとオファーが適用されます。`promotion_code` フィールドに有効な引き換えコードを含めます。**例: automatic** | | promotion_code | 文字列 (大文字、小文字を区別しない) 最大 20 文字使用可能な文字: 英字、数字、ハイフン (`-`)、アンダースコア (`_`) | `application_type` が `promotion_code` の場合に必須 | 顧客がプロモーションを引き換えるために使用するコード。すべての `free_shipping` プロモーションには有効な引き換えコードを含める必要があります。**例: SPRING20** | ### フィード処理手順 システムがフィードの各行を処理する方法を制御する操作フィールドを定義します。 | フィールド | データタイプ | 要件 | | ------ | --------------------------- | -- | | delete | Boolean (`true` or `false`) | 任意 | プロモーションの完全削除を指定するフラグ。`true` の場合、`promotion_id` で識別されるプロモーションを削除し、その行の他のすべての列は無視されます。**例: true** |