マーケティングおよび割引

マーケティングおよび割引ガイド

概要

Buy Marketing APIおよびDeal APIを使用すると、ユーザーはeBayマーケットプレイス上のセール（ディール）、販売イベント、およびトップセラー商品を見つけることができます。

ユースケース

  • セール対象商品の取得
  • マーケットプレイスのイベントの取得
  • カテゴリ内のベストセラー商品の取得
  • ウォッチ数が最も多い商品の取得
  • 特定の商品に類似した商品の取得

セール対象商品の取得

Deal APIを使用すると、開発者はeBayのセール（ディール）を検索し、詳細を取得できます。

getDealItemsを使用して、指定されたマーケットプレイス上のセール対象商品のリストを取得します。このメソッドでは、セール検索を絞り込むために以下のクエリパラメータを使用できます。

  • category_ids: 指定されたカテゴリ内のセールを取得します。
  • commissionable: コミッション対象（報酬発生対象）となる商品のセールを取得します。コミッション対象商品とは、eBay Partner Network (ePN) パートナーが宣伝することで報酬を得ることができる商品です。
  • delivery_country: 特定の国（2文字の国コードで指定）に配送可能な商品のセールを取得します。

ページネーションには、limitおよびoffsetクエリパラメータも利用可能です。

リクエストが成功すると、入力条件に一致するアイテムのリストが返されます。割引額や割引率など、セール商品に関する情報が各アイテムごとに返されます。eBay Partner Networkのアフィリエイトは、dealAffiliateWebUrlおよびitemAffiliateWebUrlフィールドを通じて返されるURLを使用して、セールまたは特定のeBayリスティングにトラフィックを誘導し、報酬を受け取ることができます。

マーケットプレイスのイベントの取得

セールの検索に加えて、Deal APIを使用すると、ユーザーはeBayの販売イベントおよびそれらのイベントに関連する商品情報を検索・取得できます。「販売イベント」とは通常、特定のグループまたはカテゴリの商品に対する割引キャンペーンを指し、セラーがより多くの顧客を引き付けることを可能にします。

以下のフローで、特定のマーケットプレイス上のイベントおよびイベント対象商品を取得できます。

  1. getEventsまたはgetEventを使用して、指定されたマーケットプレイス上の1つまたは複数のeBayイベントを取得します。各イベントについて以下の情報が返されます。
    • eventId: イベントの一意の識別子。
    • applicableCoupons: イベントに関連するクーポンのリスト（クーポンコードおよび条件を含む）。
    • startDate および endDate: イベントの開始日と終了日。
    • terms: イベントの利用規約。
  2. 取得した特定のイベントの event_id を参照し、getEventItemsを使用して、そのイベントに関連する商品情報を取得します。このメソッドでは、イベント商品検索を絞り込むために以下のクエリパラメータを使用できます。
    • category_ids: 指定されたカテゴリ内のイベント商品を取得します。
    • delivery_country: 特定の国（2文字のISO 3166国コードで指定）に配送可能なイベント商品を取得します。

ページネーションには、limitおよびoffsetクエリパラメータも利用可能です。

リクエストが成功すると、指定されたイベント内で入力条件に一致するアイテムのリストが返されます。割引額や割引率など、各イベント商品に関する情報がアイテムごとに返されます。

カテゴリ内のベストセラー商品の取得

Buy Marketing APIを使用すると、ユーザーは「ベストセラー商品」などの特定の指標に基づいてeBayの商品を取得できます。このAPIにより、バイヤーはeBay上のベストセラー商品を検索し比較することができます。

getMerchandisedProductsを使用して、指定されたカテゴリ内のベストセラー商品のリストを取得します。

検索を絞り込むために、このメソッドでは以下のクエリパラメータを使用できます。

  • metric_name (必須): 指定された指標で結果セットをフィルタリングします。現在、BEST_SELLINGのみがサポートされています。
  • category_id (必須): 特定のカテゴリで結果セットをフィルタリングします。
  • aspect_filter: アスペクト名と値のペアで結果セットをフィルタリングします。例えば、aspect_filter=Brand:Canonを使用すると、Canonブランドの商品に対するセールのみが返されます。商品のアスペクトを取得するには、fieldgroups=ASPECT_REFINEMENTを指定してBrowse APIのsearchメソッドを使用してください。
  • limit: 結果セットで返す商品の最大数。

リクエストが成功すると、入力条件に一致する商品のリストが返されます。これには、商品のePID、タイトル、ユーザーレビュー、評価が含まれます。

注意: 返された商品に関する詳細情報を取得するには、このメソッドで返されたePIDを使用してBrowse APIのsearchメソッドを使用してください。

ウォッチ数が最も多い商品の取得

Marketing APIのgetMostWatchedItemsメソッドを使用して、サイト全体、または特定のカテゴリ（category_idパラメータで指定）で最もウォッチ数が多い商品のデータを取得します。max_resultsパラメータを使用して結果セットを制限できます。

リクエストが成功すると、指定されたカテゴリ内で最もウォッチされている商品の詳細が返されます。各アイテムについて、現在の価格と送料のほか、itemId、タイトル、リスティングの残り時間などのリスティングに関する基本情報が返されます。返されるアイテムは、最新のウォッチ数情報の降順でランク付けされます。

注意: ユーザーは、レガシーなMerchandising APIのgetMostWatchedItemsメソッドを使用しても、最もウォッチされている商品を取得できます。ただし、このコールは非推奨となっており、将来的に廃止される予定です。最もウォッチされている商品を取得するには、Marketing APIへの移行が推奨されます。

特定の商品に類似した商品の取得

Marketing APIのgetSimilarItemsメソッドを使用して、特定の商品（item_id値で指定）に類似した商品のレコメンデーションを取得します。

以下のパラメータを使用して結果セットをフィルタリングできます。

  • excluded_category_ids: 指定されたカテゴリの商品を結果セットから除外します。
  • buying_option: 結果セットを特定のタイプのリスティングのみに制限します（例：固定価格リスティングのみ）。
  • filter: itemEndDateなどの様々なフィルタで結果セットを制限します。

リクエストが成功すると、検索条件に一致する類似商品が返されます。各アイテムについて、現在の価格と送料のほか、itemId、タイトル、リスティングの残り時間などのリスティングに関する基本情報が返されます。

注意: ユーザーは、レガシーなMerchandising APIのgetSimilarItemsメソッドを使用しても、類似商品を取得できます。ただし、このコールは非推奨となっており、将来的に廃止される予定です。類似商品を取得するには、Browse APIへの移行が推奨されます。

コードサンプル

特定のマーケットプレイス上のセール対象商品を取得する： 

curl -X GET "https://api.ebay.com/buy/deal/v1/deal_item?category_ids=257818" \
-H "Authorization: Bearer OAUTH_token" \
-H "X-EBAY-C-MARKETPLACE-ID:EBAY_US"

特定のマーケットプレイス上のイベントを取得する： 

curl -X GET "https://api.ebay.com/buy/deal/v1/event?limit=1" \
-H "Authorization:Bearer OAUTH_token" \
-H "X-EBAY-C-MARKETPLACE-ID:EBAY_US"

エラーハンドリング

  • getMerchandisedProductsの使用時に「無効なメトリック名（Invalid metric name）」エラーが発生した場合は、metric_nameの値がBEST_SELLINGであることを確認してください。現在、これだけがサポートされているメトリックです。
  • Deal APIの使用時に「Invalid filter for delivery_country（delivery_countryのフィルタが無効です）」というエラーが発生した場合は、delivery_countryクエリパラメータが2文字のISO 3166国コードとして入力されていることを確認してください。

ベストプラクティス

  • Deal APIを使用してeBayのセールやイベントを取得した後、バイヤー（購入アプリ）はOrder APIを活用して既存の注文を更新したり、新しい注文を作成したりできます。例えば、バイヤーはgetEventを使用してイベントに関連する利用可能なクーポンの引き換えコード（リデンプションコード）を取得し（applicableCoupon.redemptionCode）、その後Order APIのapplyCouponメソッドを使用して既存の注文にその引き換えコードを適用できます。
  • サンドボックスでBuy Marketing APIをテストするには、カテゴリID 9355を使用する必要があり、レスポンスはモックデータとなります。
トップに戻る