交渉 API（Negotiation API）
Negotiation API を使用すると、売り手は自分の出品に「興味」を示した購入者に積極的に割引オファーを送信できます。購入者がウォッチリストに追加したり、ショッピングカートに追加後に放棄した場合などに、販売者は割引オファーを送信して販売を促進できます。
バージョン: v1.1.0
ベースURL: https://api.ebay.com/sell/negotiation/v1
認証（OAuth スコープ）
この API は 認可コード（Authorization Code） フローを使用します。
| スコープ |
説明 |
https://api.ebay.com/oauth/api_scope/sell.inventory | 在庫とオファーの表示と管理 |
https://api.ebay.com/oauth/api_scope/sell.inventory.readonly | 在庫とオファーの表示 |
リソース一覧
Negotiation API は以下の 1 リソース、合計 2 エンドポイント（1 GET + 1 POST）で構成されています。
| リソース |
説明 |
数 |
| offer | 対象出品の検索と購入者へのオファー送信 | 2 |
offer — 購入者へのオファー（2 エンドポイント）
GET /find_eligible_items
findEligibleItems — 販売者の現在の出品を評価し、購入者に割引オファーを開始する対象となる出品 ID のセットを返します。1 人以上の購入者が出品に「関心」を示した場合にのみ出品 ID が返されます。
| パラメータ | 場所 | 必須 | 説明 |
|---|
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 必須 | 対象出品を検索する eBay マーケットプレイス。 |
limit | クエリ | 任意 | ページあたりの最大件数。最小: 1、最大: 200、デフォルト: 10 |
offset | クエリ | 任意 | スキップする結果の数。デフォルト: 0 |
レスポンス: 200 → PagedEligibleItemCollection / 204 / 400 / 500
POST /send_offer_to_interested_buyers
sendOfferToInterestedBuyers — 出品に興味を示した購入者に割引価格でのオファーを送信します。出品価格から一定の割合で割引するか、新しい割引価格を設定できます。
| パラメータ | 場所 | 必須 | 説明 |
|---|
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 必須 | 出品が掲載される eBay マーケットプレイス。 |
Content-Type | ヘッダー | 必須 | application/json |
リクエストボディ: CreateOffersRequest
レスポンス: 200 → SendOfferToInterestedBuyersCollectionResponse / 400 / 409 / 500
スキーマ定義（全 11 スキーマ）
オファー
CreateOffersRequest
| フィールド | 型 | 説明 |
|---|
allowCounterOffer | boolean | 購入者のカウンターオファーを許可するかどうか |
message | string | 購入者へのメッセージ |
offerDuration | TimeDuration | オファーの有効期間 |
offeredItems | array[OfferedItem] | オファーするアイテムの配列 |
OfferedItem
| フィールド | 型 | 説明 |
|---|
listingId | string | 出品 ID |
price | Amount | 割引後の価格 |
discountPercentage | string | 割引率（%） |
quantity | integer | 数量 |
Offer
| フィールド | 型 | 説明 |
|---|
offerId | string | オファー ID |
offerStatus | string | オファーステータス |
offerType | string | オファータイプ |
allowCounterOffer | boolean | カウンターオファー許可 |
message | string | メッセージ |
offerDuration | TimeDuration | 有効期間 |
offeredItems | array[OfferedItem] | オファーアイテム |
buyer | User | 購入者情報 |
initiatedBy | string | 開始者 |
creationDate | string | 作成日時 |
lastModifiedDate | string | 最終更新日時 |
revision | string | リビジョン |
SendOfferToInterestedBuyersCollectionResponse
| フィールド | 型 | 説明 |
|---|
offers | array[Offer] | 送信されたオファーの配列 |
対象アイテム
PagedEligibleItemCollection
| フィールド | 型 | 説明 |
|---|
eligibleItems | array[EligibleItem] | 対象アイテムの配列 |
href | string | 現在の結果の URI |
next | string | 次ページの URI |
prev | string | 前ページの URI |
offset | integer | オフセット |
limit | integer | 最大件数 |
total | integer | 総数 |
EligibleItem
| フィールド | 型 | 説明 |
|---|
listingId | string | 出品 ID |
共通型
Amount
| フィールド | 型 | 説明 |
|---|
currency | string | 通貨コード |
value | string | 金額 |
TimeDuration
| フィールド | 型 | 説明 |
|---|
unit | string | 時間単位 |
value | integer | 値 |
User
| フィールド | 型 | 説明 |
|---|
maskedUsername | string | マスクされたユーザー名 |
Error
| フィールド | 型 | 説明 |
|---|
category | string | エラーカテゴリ |
domain | string | エラードメイン |
errorId | integer | エラー ID |
message | string | 短いメッセージ |
longMessage | string | 詳細メッセージ |
inputRefIds | array[string] | 入力参照 ID |
outputRefIds | array[string] | 出力参照 ID |
parameters | array[ErrorParameter] | エラーパラメータ |
subdomain | string | エラーサブドメイン |
ErrorParameter
| フィールド | 型 | 説明 |
|---|
name | string | パラメータ名 |
value | string | パラメータ値 |
エンドポイント一覧（全 2 エンドポイント）
| メソッド |
エンドポイント |
operationId |
説明 |
| GET | /find_eligible_items | findEligibleItems | 対象出品を検索 |
| POST | /send_offer_to_interested_buyers | sendOfferToInterestedBuyers | 購入者にオファーを送信 |
