SP-APIフィードAPI（Feeds API）の使い方｜JSON_LISTINGS_FEEDへの移行と実装手順

Amazon SP-APIのフィードAPI（Feeds API）は、商品情報や価格・在庫をまとめてAmazonへ送るためのAPIです。ただし2025年に旧来のXML・フラットファイル系リスティングフィードが廃止されたため、いま実装するなら送信フォーマットをJSONに切り替える前提が出発点になります。この記事では現行のv2021-06-30を対象に、6つのオペレーションと実際のレート制限、送信手順、ペイロード構造、処理レポートのエラーコードまでを公式のAPIモデルとスキーマに沿って整理しました。

まとめ

• 現行版はFeeds API v2021-06-30。旧v2020-09-04で必要だったフィードドキュメントの暗号化・復号処理は不要になりました。
• 商品リスティング系のXML・フラットファイルフィード（POST_PRODUCT_DATAなど）は2025年7月31日に廃止済みで、移行先はJSON_LISTINGS_FEEDかListings Items APIの2択です。
• 送信の流れはcreateFeedDocument→署名付きURLへPUT→createFeed→getFeed→getFeedDocumentの5段階。署名付きURLの有効期限は5分しかありません。
• 1フィードに載せられるメッセージは最大25,000件。1,500件を超える更新はフィード側が有利になります。
• 数件を即時反映したいならListings Items API（毎秒5リクエスト）、大量一括ならJSON_LISTINGS_FEEDという使い分けです。

以下、各段階の具体的な要求内容と判断基準を、公式APIモデルの記述に沿って説明します。

Feeds API v2021-06-30の6オペレーションとレート制限

Feeds APIは6つのオペレーションで構成されます。公式APIモデル（feeds_2021-06-30.json）が示す既定のレート制限には、オペレーション間で240倍以上の開きがあり、この差がそのまま設計上の制約になります。まず数値を押さえてください。

表の値は既定値にすぎません。公式モデルは、実際に適用されたレートがレスポンスヘッダのx-amzn-RateLimit-Limitで返ること、取引量の大きい出品者にはより高い値が割り当てられる場合があることを明記しています。スリープ間隔をハードコードするより、このヘッダを読んで待ち時間を決めるほうがスロットリングを踏まずに済むはずです。なおcancelFeedで取り消せるのはprocessingStatusがIN_QUEUEのフィードだけで、処理が始まったあとは取り消せません。

XML・フラットファイル系フィードの廃止とJSON形式への移行

廃止対象のフィードタイプと期日の変遷

Amazonは2024年3月18日、XMLおよびフラットファイル形式のリスティングデータをFeeds APIで送信する方式の廃止を公表しました。対象はPOST_PRODUCT_DATA、POST_INVENTORY_AVAILABILITY_DATA、POST_PRODUCT_PRICING_DATA、POST_PRODUCT_IMAGE_DATA、POST_PRODUCT_OVERRIDES_DATA、POST_PRODUCT_RELATIONSHIP_DATA、POST_FLAT_FILE_LISTINGS_DATA、POST_FLAT_FILE_INVLOADER_DATA、POST_FLAT_FILE_PRICEANDQUANTITYONLY_UPDATE_DATAなどで、価格・在庫・親子関係・画像を含みます。告知の箇条書きは13項目ですが、POST_FLAT_FILE_LISTINGS_DATAが2回掲載されているため実質12種です。

当初のサンセット期日は2025年3月31日でした。その後、公式チェンジログで2025年6月30日、さらに2025年7月31日へと2度延期されています。2024年以前に書かれた実装記事やサンプルコードはPOST_PRODUCT_DATAを前提にしているものが多く、そのまま写経しても動きません。注意したいのは失敗の出方で、チェンジログによれば送信リクエスト自体は通り、getFeedの応答でprocessingStatusがFATALになる形で分かります。呼び出し時点でエラーが返るわけではないため、レポートまで見ていないと原因に気づけません。なお、この廃止はセラーセントラルから出品者が直接アップロードするファイルには影響せず、あくまでFeeds API経由の話です。

Listings Items APIとJSON_LISTINGS_FEEDの使い分け基準

移行先は2つあり、選択基準は「1回の処理で何件触るか」と「同期エラーが要るか」の2点でほぼ決まります。

数件から数十件のSKUを即時に反映したい用途でFeeds APIを選ぶのは設計ミスです。createFeedはオペレーション単位では毎秒0.0083リクエストしか通らず（フィードタイプ別の実効枠は後述します）、結果が分かるのは処理レポートを取得したあとになります。この用途ではListings Items APIのpatchListingsItemが毎秒5リクエストで、しかもエラーがその場で返ります。バリデーションだけ先に走らせる検証モードも使えるので、投入前に要件不足を潰せる点も見逃せません。

逆に大量更新ではフィードが有利です。公式FAQは1,500件を超える更新であればJSON_LISTINGS_FEEDで一括送信するよう推奨しており、1フィードに載せられるメッセージ数の上限は公式スキーマのmaxItemsで25,000件と定義されています。フィードドキュメント1本のサイズ上限は約10MBです（公式FAQは10MB、ベストプラクティスは10MiB＝10,485,760バイトと表記）。REST APIとGraphQLの違いと使い分けで扱った選定の考え方と同じく、ここでも判断軸は呼び出し回数と応答の粒度になります。

フィード送信の実装手順

公式ユースケースガイドは送信を複数のステップに分けて説明していますが、API呼び出しの単位でまとめると5段階です。以下では手順を3つのh3に分けて追います。

フィードドキュメントの作成と署名付きURLへのアップロード

最初にcreateFeedDocumentを呼び、これから送るファイルの置き場所を確保します。リクエストにはcontentTypeだけを渡してください。文字コードはUTF-8が推奨されています。

POST https://sellingpartnerapi-fe.amazon.com/feeds/2021-06-30/documents
x-amz-access-token: <LWAアクセストークン>
Content-Type: application/json

{
  "contentType": "application/json; charset=UTF-8"
}

レスポンスでfeedDocumentIdと署名付きURLが返ります。このURLの有効期限は5分です。公式モデルにも「このURLは5分後に失効する」と明記されているため、トークン取得やファイル生成を挟んで手間取ると、アップロード時点で切れています。ファイルを先に用意してからcreateFeedDocumentを呼ぶ順序にしてください。日本のマーケットプレイスを扱う場合、エンドポイントは極東リージョンのsellingpartnerapi-fe.amazon.comです。

次に、受け取ったURLへファイルの中身をPUTします。ここで指定するContent-Typeは、createFeedDocumentで申告した値と完全に一致させてください。ずれると後続の処理でエラーになります。

createFeedによるフィード登録

アップロードが終わってから、createFeedでフィードを登録します。公式モデルのinputFeedDocumentIdの説明にも「createFeedオペレーションを呼ぶ前にフィードドキュメントの内容をアップロードすること」と書かれており、順序が逆だと空のファイルが処理されてしまいます。

POST https://sellingpartnerapi-fe.amazon.com/feeds/2021-06-30/feeds

{
  "feedType": "JSON_LISTINGS_FEED",
  "marketplaceIds": ["A1VC38T7YXB528"],
  "inputFeedDocumentId": "<createFeedDocumentが返したfeedDocumentId>"
}

marketplaceIdsのA1VC38T7YXB528はAmazon.co.jpの識別子です。公式APIモデルの応答例にも、このIDとmarketplaceName「Amazon.co.jp」が対で記載されています。呼び出しが成功するとfeedIdが返ります。

処理状況の確認と処理レポートの取得

フィードの状態はgetFeedで確認します。processingStatusが取り得る値はIN_QUEUE、IN_PROGRESS、DONE、CANCELLED、FATALの5つで、DONE・CANCELLED・FATALのいずれかになれば処理は終わりです。ただし終了ステータスは個々のレコードの成否を表しません（詳しくはよくある質問を参照）。

処理が終わるとresultFeedDocumentIdが得られるので、これをgetFeedDocumentに渡してレポートのダウンロードURLを取得してください。レスポンスにcompressionAlgorithmとしてGZIPが返る場合があり、そのときは展開してから読む必要があります。この項目が返らなければ、そのままダウンロードできます。

状態確認をgetFeedのポーリングで回すのは、レートの面では毎秒2リクエストと余裕があるものの、空振りの呼び出しが増えます。公式のユースケースガイドが推奨するのは、Notifications APIでFEED_PROCESSING_FINISHEDイベントを購読する方式です。SP-APIの配信先はSQSやEventBridgeであってHTTPエンドポイントではありませんが、完了を待ち受ける側に処理を寄せるという発想はIncoming Webhookとは？仕組みとSlack・Discordでの使い方を解説で扱ったpush型の通知と共通しています。

JSON_LISTINGS_FEEDのペイロード構造

headerとmessagesの必須項目

JSON_LISTINGS_FEEDの中身は、公式スキーマ（listings-feed-schema-v2.json）でheaderとmessagesの2部構成と定められています。headerの必須項目はsellerIdとversionで、versionは文字列の「2.0」固定です。issueLocaleを省略した場合は、先頭マーケットプレイスの既定言語でエラーメッセージが返ります。

headerにreportを付けると、処理レポートにListings Items APIの出力を同梱できます。includedDataに指定できるのはsummaries、attributes、issues、offers、fulfillmentAvailability、procurement、relationships、productTypesの8種で、apiVersionは2021-08-01のみ指定できます。レポートを読んだあとに現在値を確認するための追加リクエストを省ける仕組みです。

{
  "header": {
    "sellerId": "<出品者ID>",
    "version": "2.0"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "MY-SKU-001",
      "operationType": "PATCH",
      "productType": "LUGGAGE",
      "patches": [
        {
          "op": "replace",
          "path": "/attributes/fulfillment_availability",
          "value": [
            { "fulfillment_channel_code": "DEFAULT", "quantity": 10 }
          ]
        }
      ]
    }
  ]
}

UPDATE・PARTIAL_UPDATE・PATCH・DELETEの選択

messagesの各要素にはmessageId、sku、operationTypeの3つが必須です。DELETEで出品を取り下げる場合も、この3項目は省略できません。operationTypeの選択を誤ると意図しない属性の消失につながります。UPDATEは属性一式を送る全置換で、送らなかった任意属性は削除されてしまいます。在庫数だけを直したいときにUPDATEを選ぶと、他の属性を巻き添えにするので注意してください。

部分更新にはPARTIAL_UPDATEかPATCHを使います。両者の関係はスキーマ原文に明記されており、PARTIAL_UPDATEはPATCHでopにreplaceを指定した場合と等価です。PATCHのopにはadd、replace、merge、deleteの4種があり、pathで対象属性を名指しします。在庫や価格のような単一属性の定期更新なら、影響範囲が最も狭いのはPATCHのreplaceでしょう。

あわせてrequirementsという項目があり、LISTING、LISTING_PRODUCT_ONLY、LISTING_OFFER_ONLYから選べます。既定値はLISTINGで、商品情報と販売条件の両方を扱う指定です。商品情報だけを扱うならLISTING_PRODUCT_ONLY、既存ASINへの相乗り出品で商品情報を触りたくないならLISTING_OFFER_ONLYを指定して販売条件だけに絞ります。

処理レポートの読み方とエラー対応

summaryと2層のissuesの構造

処理レポートのトップレベルは、header、issues、summary、itemsの4部で構成されています。まず見るべきはsummaryで、errors、warnings、messagesProcessed、messagesAccepted、messagesInvalidのカウンタに加え、itemSummary（items・errors・warnings）が入ります。messagesProcessedとmessagesAcceptedの差が、そのまま弾かれた件数です。公式の例では4件処理して2件受理、2件不正という結果に対してerrorsが3となっており、1メッセージが複数のエラーを持つと分かります。エラー件数と失敗SKU数は一致しません。

注意すべきはissuesが2層に分かれている点です。トップレベルのissuesはフィード投入を阻害した問題を持ち、messageId、sku、code、severity、message、attributeNameの組で返ります。一方、headerでreport.includedDataを指定したときだけ現れるitems配列の下にも、items[].issuesという別のissuesが存在します。こちらはListings Items API側の出力で、フィールド名がattributeNames（複数形）になり、categoriesやenforcementsを伴うのが違いです。トップレベルだけを走査する実装では、後者を丸ごと取り逃してしまうので注意してください。

severityにはERROR、WARNING、INFOの3種があります。またissuesで必須なのはseverityとmessageだけで、messageIdはスキーマ原文に「メッセージに起因しないエラー（フィード書式の不正など）では返らない」と明記されています。再送信対象をmessageIdで機械的に絞り込む実装には、messageIdが無いケースのフォールバックを用意しておいてください。

代表的なエラーコードと切り分け

公式スキーマの例に載っているコードは、実装初期に遭遇しやすいものです。出現箇所が2層のどちらかで対応の緊急度が変わります。

WARNINGを「受理されたので後回しでよい」と読むのは危険です。公式の例では18027にenforcementsが付き、actionsとしてSEARCH_SUPPRESSED、つまり検索結果からの非表示が記録されています。フィードとしては成功していても、商品が見つからない状態に陥っているわけです。WARNINGでも実害の有無をenforcementsで確認してください。

90220と99022はいずれも属性要件の不一致です。Amazonは移行にあたって「JSONスキーマの必須属性はカテゴリXSDより増えて見える場合がある」と説明していますが、これは要件が厳しくなったのではなく、条件付き必須が正確に表現されるようになった結果です。決め打ちの属性セットを使い回さないでください。

レート制限を前提としたバッチ設計

実効スループットを決める4階層のレート制限

Feeds APIの設計で最も誤解を招きやすいのが、createFeedの毎秒0.0083リクエストという値の扱いです。逆数を取ると約120秒なので、これだけを見て「フィードは2分に1本しか投げられない」と結論づけたくなります。ところがSP-APIのレート制限は、アプリケーション単位・出品者単位・オペレーション単位・データタイプ単位の4階層で構成されており、0.0083はそのうちオペレーション単位の既定値にすぎません。

JSON_LISTINGS_FEEDにはデータタイプ単位の別枠があります。公式チェンジログは「JSON_LISTINGS_FEEDのレート制限はcreateFeedオペレーションのレート制限とは異なる」と明記したうえで、フィードあたりの上限を10,000件から25,000件へ引き上げたと告知しました。AmazonのSolutions Architectが公開した資料では、JSON_LISTINGS_FEEDの出品者単位の日次スループットを3,600万件としています。1フィード25,000件で割ると1日あたり約1,440本、およそ1分に1本という計算です。

したがってオペレーション単位の0.0083だけを根拠に上限を見積もると、実力を半分近く低く見積もる結果になります。とはいえ割り当ては出品者やアプリケーションによって変わるため、固定値を前提に組むのは避けてください。実装ではx-amzn-RateLimit-Limitヘッダの値を読んで待ち時間を決め、公式のフィードタイプ別レート制限を併せて確認するのが確実です。

再送信とバースト枠の配分

いずれの階層で見ても、SKU単位でフィードを作る実装は成立しません。更新対象をいったんキューに溜め、一定件数または一定時間でまとめて1ファイルにしてから送る形にします。バーストの15回分は平常運転で使い切らず、障害時の再送用に残しておくとリカバリのときに詰まりません。

再送信の設計にも注意点があります。エラーになったメッセージだけを抜き出して再送するのが基本で、ファイル全体を丸ごと投げ直すのは避けましょう。全件再送は貴重な投入枠を消費するうえ、既に受理済みのSKUに対して不要な更新を走らせることになるためです。issues配列のskuとmessageIdから対象を絞り込めるので、この情報をそのまま再送ファイルの生成に使います。前述のとおりmessageIdが返らないケースがあるため、skuを補助キーにしておくと取りこぼしを防げます。

検証環境については、Feeds APIの公式APIモデルに全6オペレーション分のサンドボックス応答定義（x-amzn-api-sandbox）が含まれています。ただしサンドボックスが返すのは固定の静的応答なので、実データの処理結果まで再現されるわけではありません。属性要件の充足やエラーコードの確認は、少量のテスト用SKUで本番相当の検証を行う計画にしておきましょう。物流側まで含めた運用設計を検討する場合は、Amazon Supply Chain Services（ASCS）の全体像と統合物流価値で扱った在庫配置の考え方も判断材料になります。

よくある質問

フィードAPIとレポートAPI、Data Kiosk APIの違いは何ですか

データの向きと取得方法が異なります。Feeds APIは出品者からAmazonへデータを送るためのAPIで、公式モデルの説明も「出品パートナーに代わってAmazonへデータをアップロードする」と定義しています。売上や在庫の実績データをAmazonから取り出すのはReports APIの役割です。Data Kiosk APIはさらに新しい仕組みで、GraphQLのクエリで分析用データを問い合わせる方式を採ります。送るならFeeds、定型の帳票を取るならReports、集計データを柔軟に問い合わせるならData Kiosk、と整理すると迷いません。なお処理結果のレポートを取得する部分だけは、Feeds API内のgetFeedDocumentが担当します。

1回のフィードで複数のマーケットプレイスへ送れますか

同じリージョン内であれば送れます。createFeedのmarketplaceIdsは配列で、公式モデルの定義は最小1件・最大25件です。日本・オーストラリア・シンガポールのように極東リージョンで揃う範囲なら、同じフィードドキュメントを一度に適用できます。ただし米国は北米リージョンでエンドポイント自体が別になるため、日本と米国を1回のフィードにまとめることはできません。属性要件もマーケットプレイスごとに異なる場合があるので、まとめる前に商品タイプ定義APIで要件を突き合わせておいてください。

processingStatusがDONEなら全件成功したと考えてよいですか

いいえ。DONEはフィード全体の処理が完了したことを示すだけで、個々のレコードの成否とは別です。公式スキーマの例でも、4件処理して受理は2件という結果でフィード自体は正常終了しています。処理レポートのsummaryにあるmessagesAcceptedとmessagesInvalid、それにitemSummaryのwarningsまで必ず確認してください。

v2021-06-30なら暗号化の実装はもう不要ですか

API仕様として課されていた暗号化・復号の実装は不要になりました。旧v2020-09-04のモデルにはFeedDocumentEncryptionDetailsが定義され、standardにAES、initializationVectorにCBC用のベクトルを指定して「ドキュメント内容のクライアントサイド暗号化・復号」を必須としていましたが、現行モデルにこれらの項目はありません。ただし公式ガイドは保存時の暗号化を開発者の責任として引き続き求めており、復号済みの処理レポートを一時的にでもディスクへ平文で置かないよう明記しています。消えたのはドキュメント本体を自前でAES暗号化する手間であって、データ保護の義務ではありません。

広告で使う「データフィード」とは別のものですか

別物です。この記事のフィードAPIはAmazon SP-APIの一機能で、Amazonへ商品情報を送るためのものです。一方、検索連動型広告やショッピング広告で使う「データフィード」は、各広告媒体の仕様に合わせて商品データを整形・最適化する話で、対象も目的も異なります。後者についてはDFO（データフィード最適化）とは？ツール料金比較と媒体別フィード仕様の実務を参照してください。

関連記事

• Incoming Webhookとは？仕組みとSlack・Discordでの使い方を解説
• REST APIとGraphQLの違いと使い分け｜選定基準と運用コスト
• Amazon Supply Chain Services（ASCS）の全体像と統合物流価値
• DFO（データフィード最適化）とは？ツール料金比較と媒体別フィード仕様の実務
• 在庫管理システムとは？仕組み・機能・種類・費用と選び方を初心者向けに徹底解説