クーパン Open API：価格・在庫の更新に別々のAPI呼び出しが必要な理由

クーパンのOpen APIでは、公開中の商品の価格や在庫を、その商品を作成したのと同じ商品呼び出しから変更することはできません。商品がいったん承認されると、価格と在庫はそれぞれ専用の商品（アイテム）単位のエンドポイントを経由するようになります。商品編集のパスは、設計上、これらのフィールドを黙って無視するのです。「商品更新」用のフィード一本ですべてを同期できるという前提でクーパン連携を設計しようとしているなら、まさにその前提が、多くの実装が破綻するポイントになります。

これは、めったに遭遇しない例外的なケースではありません。クーパンに初めて取り組むチームが「更新したのに反映されない」と混乱する、最も一般的な原因です。そして、公開中のカタログを実際に運用するのに、どれだけの連携作業が本当に必要になるかを左右します。以下では、なぜこの分離が存在するのか、そしてそれが自社開発か外部購入かの判断にどう影響するのかを整理します。

商品はいくつかの状態を移り変わり、状態ごとに許される変更が異なる

クーパンの商品は、更新を投げ込めばよい静的なレコードではありません。クーパンの商品のライフサイクルはいくつかの状態を通過します。APIで変更できる内容は、その時点での商品の状態によって決まるのです。

大まかに言うと、商品はまず「一時保存」の状態から始まります。これは自由に編集できる下書きです。ここから承認申請を行い、クーパンが審査します。承認された後にはじめて、その商品は公開・販売可能な状態になります。ツール開発において重要なのは、一部の操作は特定の状態でしか有効でないという点です。たとえば承認申請は、保存済みでまだ申請していない下書きからのみ可能です。すでに承認済みのものに対して承認を再申請することはできませんし、承認済みの商品を、まだ編集中の下書きであるかのように扱うこともできません。

「クーパンで自分の更新は反映されるか？」その答えは1つではありません。商品の状態次第だからです。呼び出しを行った時点での商品の状態によって、答えは変わります。状態を無視するコネクタは、商品作成時には問題なく動作します。ところが商品が公開された瞬間に、変更を静かに反映しなくなるのです。

承認後は、商品編集の呼び出しでは価格・在庫が反映されない

ここが具体的な落とし穴です。商品を作成し、形を整えるのに使った呼び出し、つまりタイトル・画像・仕様・オプションを扱う商品編集のパスは、承認済みの商品の価格や在庫を更新しません。これらのフィールドをそのパス経由で送っても、パイプラインを止めるような目立つエラーは出ません。ただ変更が反映されないだけです。

これはバグではなく、意図された設計です。クーパンは「その商品が何であるか」という関心事と、「今それがどう売られているか」という関心事を分離しています。説明的な属性は商品レコードとともに扱われますが、商業的な属性（価格や販売可能数量）は、専用の管理されたエンドポイントを通じて動く、リアルタイムの運用レバーとして扱われます。クーパン側から見れば、これにより価格・在庫の変更が高速で、追跡可能で、カタログの再承認から独立したものになります。一方、あなたの側から見れば、「何かを変えたければ商品を編集すればよい」という素朴な思考モデルが、最も頻繁に変更する2つのフィールドについて、まさに間違っているということを意味します。

韓国での価格がクーパン上では古いまま張り付いているのに、正となるシステム（source of truth）では新しい数字が表示されている、そんな経験がチームにあるとしたら、その原因はほぼ間違いなくこの分離です。更新が誤った呼び出しにルーティングされ、その誤った呼び出しがリクエストを受理しながらフィールドを反映しなかったのです。

価格と在庫には、それぞれ専用の商品（アイテム）単位の呼び出しがある

商品編集のパスでは触れられない部分を変更するには、同期ロジックが変更の種類ごとに正しい専用エンドポイントへルーティングしなければなりません。実務上、扱うべき関心事は次の3つに分かれます。

• 元の価格（割引の基準となる価格） — 割引を計算する基準となる参照価格です。これには専用の呼び出しがあります。
• 販売価格 — 顧客が実際に支払う価格です。これは元の価格とは別の呼び出しになります。
• 販売可能数量（在庫） — クーパンが在庫ありとして表示する数量です。これもまた別個の呼び出しです。

実際には、あなた側の1つの業務イベントが、複数のクーパン呼び出しに展開されることがよくあります。「このSKUをプロモーションにかける」というのは、割引基準となる価格と販売価格の更新、つまり2つの別々のリクエストを意味するかもしれません。「入荷したので在庫を補充する」というのは在庫の呼び出しであり、どちらの価格呼び出しとも無関係です。連携システムは、1つのペイロードですべてを賄えると想定できません。それぞれの変更を分解し、正しい場所へ送る必要があります。

だからこそ、自動化に着手する前に、対象となる商品を誰が管理する主体なのかを気にかけておくことが重要になります。ロケットグロースのもとでは、在庫はあなたが所有し、保管と配送をクーパンが担います。したがってAPIが送り込む数量は、あなたのERPが信じている数字ではなく、倉庫に物理的に存在する数量と一致させなければなりません。

更新はオプション単位で行われる ― そしてそのIDは承認後にしか存在しない

他のマーケットプレイス向けに作られた連携をつまずかせる、もう1つの構造的な事実があります。クーパンでの日常的な更新は、親商品ではなく、オプション単位の識別子をキーにして行われるという点です。

1つの商品には複数のオプション（サイズ、カラー、セット数など）を持たせることができます。価格と在庫は、商品全体ではなく、各オプションの属性です。そのため、専用の価格・在庫呼び出しは、オプション単位のアイテムIDに対して動作します。そしてここが落とし穴なのですが、このIDはクーパンによって生成され、商品が承認された後にしか存在しません。作成時点では、あなたはこのIDを知り得ないのです。

つまり、正しく作られた実装は、単純なフィード送信ツールが決してやらないことを行わなければなりません。承認後に、クーパンが生成したオプションIDを読み取って保存する必要があるのです。その後の日常的な価格・在庫の更新は、すべてこれらのIDを宛先とします。この手順を飛ばすと、更新を送る有効な宛先がなくなります。これもまた、正常に作成された商品が、それでも更新を一度も受け取れないという事態のもう1つのパターンです。すでにクーパンから運用データを取得しているなら、これは注文・在庫レベルでOpen APIが実際に何を提供しているのかという、より大きな全体像へとつながります。

現実的な実装に本当に必要なもの

連携を自社開発するなら、正直に見積もった作業範囲は「商品フィード1本」よりずっと大きくなります。公開中のクーパンのカタログを正確に保つコネクタには、少なくとも以下が必要です。

1. 単一のプッシュではなく、下書き → 承認申請 → 承認済み のライフサイクルを扱う商品作成フロー。
2. 商品がいつ公開されたかを検知する承認ステータスの監視機構。この状態遷移によってオプションIDと価格・在庫のエンドポイントが解放されるためです。
3. 価格、販売価格、在庫、配送の各変更を、それぞれ正しい専用の呼び出しへ送る属性ごとの更新ルーティング。決してすべてを商品編集のパス経由で送ってはいけません。
4. 承認後に取得した、クーパン生成のオプションIDの保管。日常的な更新が有効な宛先を持てるようにするためです。

これらは、それぞれ単独で見れば特別なものではありません。問題は、「単純な」フィード連携がすでに本番稼働し、静かに更新を取りこぼし始めた後になって、これらを1つずつ本番で対処することになる点にあります。

購入判断で検証すべきこと

自社開発の代わりに、既製のマルチチャネルコネクタを購入するなら、そのリスクは、1つの更新パスですべてを行えるマーケットプレイスを前提に設計されている可能性があることです。こうしたツールの多くは、単一の「商品更新」呼び出しを想定しており、商品が公開された瞬間にクーパンで静かに同期のずれを起こします。

クーパンでどんなツールに頼る前にも、次の3点を具体的に検証してください。

• 承認後の価格と在庫を、商品編集の呼び出しではなく、別個の商品（アイテム）単位の操作を通じて更新すること。
• 承認後にクーパンのオプション単位のIDを取得・保管し、それらを宛先として更新を送ること。
• **状態を認識できる（state-aware）**こと。すなわち、下書きと承認済みの商品の違いを理解し、両者を同じものとして扱わないこと。

ベンダーがこれらに明確に答えられないなら、そのツールは商品作成は問題なくこなしても、その後は韓国での価格と在庫を同期のずれたまま放置すると考えてください。これは自動化がない状態よりも厄介です。なぜなら、その失敗は静かに進行するからです。

よくある質問

なぜクーパンは、商品呼び出しですべてを更新させてくれないのですか？ クーパンが説明的な属性（その商品が何であるか）と、商業的な属性（価格と在庫）を分離しているからです。価格と在庫を専用のエンドポイントに置くことで、カタログの承認を再度トリガーせずに、これらを素早く変更できます。これは制約ではなく、意図的な設計上の選択です。

価格を間違った呼び出しで送ると、エラーは出ますか？ たいていは目立つエラーは出ません。リクエストは受理されますが、価格や在庫のフィールドは反映されません。だからこそ、この現象は非常にわかりにくいのです。エラーがないことで、チームは更新が成功したと思い込んでしまいます。

何かを更新する前に、オプションIDは必要ですか？ 日常的な価格・在庫の更新については、必要です。これらの呼び出しはオプション（アイテム）単位で動作し、オプションIDは承認後にクーパンによって生成されます。ツールは、まずそれを読み取って保存しておかなければなりません。

正確なエンドポイントやフィールド名は、どこで確認できますか？ 本記事は、あくまで平易な言葉で全体像を示す地図にすぎません。正確なエンドポイントの構文、フィールド名、リクエスト形式は、クーパンの公式開発者ドキュメントに記載されており、時とともに変更されます。実装前には、必ず最新の一次情報と照らし合わせて確認してください。