api-specs/sell_negotiation_v1_oas3.yaml
openapi: 3.0.0
info:
title: Negotiation API
description: 'The <b>Negotiations API</b> gives sellers the ability to proactively send discount offers to buyers who have shown an "interest" in their listings. <br><br>By sending buyers discount offers on listings where they have shown an interest, sellers can increase the velocity of their sales. <br><br>There are various ways for a buyer to show <i>interest </i> in a listing. For example, if a buyer adds the listing to their <b>Watch</b> list, or if they add the listing to their shopping cart and later abandon the cart, they are deemed to have shown an interest in the listing. <br><br>In the offers that sellers send, they can discount their listings by either a percentage off the listing price, or they can set a new discounted price that is lower than the original listing price. <br><br>For details about how seller offers work, see <a href="/api-docs/sell/static/marketing/offers-to-buyers.html" title="Selling Integration Guide">Sending offers to buyers</a>.'
contact:
name: 'eBay Inc,'
license:
name: eBay API License Agreement
url: 'https://go.developer.ebay.com/api-license-agreement'
version: v1.1.0
servers:
- url: 'https://api.ebay.com{basePath}'
description: Production
variables:
basePath:
default: /sell/negotiation/v1
paths:
/find_eligible_items:
get:
tags:
- offer
description: 'This method evaluates a seller''s current listings and returns the set of IDs that are eligible for a seller-initiated discount offer to a buyer. A listing ID is returned only when one or more buyers have shown an "interest" in the listing. If any buyers have shown interest in a listing, the seller can initiate a "negotiation" with them by calling sendOfferToInterestedBuyers, which sends all interested buyers a message that offers the listing at a discount. For details about how to create seller offers to buyers, see Sending offers to buyers.'
operationId: findEligibleItems
parameters:
- name: limit
in: query
description: 'This query parameter specifies the maximum number of items to return from the result set on a page in the paginated response. Minimum: 1 Maximum: 200 Default: 10'
required: false
schema:
type: string
- name: offset
in: query
description: 'This query parameter specifies the number of results to skip in the result set before returning the first result in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 results from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set. Default: 0'
required: false
schema:
type: string
- name: X-EBAY-C-MARKETPLACE-ID
in: header
description: 'The eBay marketplace on which you want to search for eligible listings. For a complete list of supported marketplaces, see Negotiation API requirements and restrictions.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PagedEligibleItemCollection'
'204':
description: No Content
'400':
description: Bad Request
x-response-codes:
errors:
'150001':
domain: API_NEGOTIATION
category: REQUEST
description: Mandatory headers are missing.
'150002':
domain: API_NEGOTIATION
category: REQUEST
description: 'The marketplace value {marketplaceId} is not supported. The supported values are: {marketplaceIds}'
'150003':
domain: API_NEGOTIATION
category: REQUEST
description: 'Invalid limit. Limit should be between {minLimit} and {maxLimit}.'
'150004':
domain: API_NEGOTIATION
category: REQUEST
description: Invalid offset. Offset cannot be less than 0.
'500':
description: Internal Server Error
x-response-codes:
errors:
'150000':
domain: API_NEGOTIATION
category: APPLICATION
description: 'Internal error. Please try the call again after a minute or two. If the error persists, contact eBay developer support for assistance.'
security:
- api_auth:
- 'https://api.ebay.com/oauth/api_scope/sell.inventory.readonly'
- 'https://api.ebay.com/oauth/api_scope/sell.inventory'
/send_offer_to_interested_buyers:
post:
tags:
- offer
description: 'This method sends eligible buyers offers to purchase items in a listing at a discount. When a buyer has shown interest in a listing, they become "eligible" to receive a seller-initiated offer to purchase the item(s). Sellers use findEligibleItems to get the set of listings that have interested buyers. If a listing has interested buyers, sellers can use this method (sendOfferToInterestedBuyers) to send an offer to the buyers who are interested in the listing. The offer gives buyers the ability to purchase the associated listings at a discounted price. For details about how to create seller offers to buyers, see Sending offers to buyers.'
operationId: sendOfferToInterestedBuyers
parameters:
- name: X-EBAY-C-MARKETPLACE-ID
in: header
description: 'The eBay marketplace on which your listings with "eligible" buyers appear. For a complete list of supported marketplaces, see Negotiation API requirements and restrictions.'
required: true
schema:
type: string
requestBody:
description: Send offer to eligible items request.
content:
application/json:
schema:
description: Send offer to eligible items request.
$ref: '#/components/schemas/CreateOffersRequest'
required: false
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SendOfferToInterestedBuyersCollectionResponse'
'400':
description: Bad Request
x-response-codes:
errors:
'150001':
domain: API_NEGOTIATION
category: REQUEST
description: Mandatory headers are missing.
'150002':
domain: API_NEGOTIATION
category: REQUEST
description: 'The marketplace value {marketplaceId} is not supported. The supported values are: {marketplaceIds}'
'150005':
domain: API_NEGOTIATION
category: REQUEST
description: 'Offer contains multiple listings {listingIds}.'
'150006':
domain: API_NEGOTIATION
category: REQUEST
description: Request cannot be null/empty.
'150007':
domain: API_NEGOTIATION
category: REQUEST
description: Both offer price and discount percentage cannot be present in the request.
'150008':
domain: API_NEGOTIATION
category: REQUEST
description: 'Price must be at least {minPercentageDifference} less than your Buy It Now price.'
'150009':
domain: API_NEGOTIATION
category: REQUEST
description: 'Invalid value for {fieldName}. {additionalInfo}'
'150027':
domain: API_NEGOTIATION
category: REQUEST
description: 'Offer is invalid. Please specify a valid duration of {durationValue} {durationUnit}'
'409':
description: Conflict
x-response-codes:
errors:
'150010':
domain: API_NEGOTIATION
category: BUSINESS
description: Invalid message. Message cannot contain HTML or blocked words and cannot exceed maximum character limit of 2000.
'150011':
domain: API_NEGOTIATION
category: BUSINESS
description: 'Invalid listingId {listingId}. The listing for this offer has ended.'
'150012':
domain: API_NEGOTIATION
category: BUSINESS
description: 'Invalid listingId {listingId}. No such listing for this seller.'
'150013':
domain: API_NEGOTIATION
category: BUSINESS
description: 'Invalid listingId {listingId}. {additionalInfo}'
'150014':
domain: API_NEGOTIATION
category: BUSINESS
description: 'Current available quantity for this listing {listingId} is less than the offer quantity.'
'150015':
domain: API_NEGOTIATION
category: BUSINESS
description: 'Invalid price for listing {listingId}. Minimum offer price of {minPrice} not met.'
'150016':
domain: API_NEGOTIATION
category: BUSINESS
description: 'Invalid price for listing {listingId}. Price value exceeds the listing price.'
'150017':
domain: API_NEGOTIATION
category: BUSINESS
description: 'Listing {listingId} does not support offer.'
'150018':
domain: API_NEGOTIATION
category: BUSINESS
description: 'Offer is invalid. A best offer currently exists on the listing {listingId}.'
'150019':
domain: API_NEGOTIATION
category: BUSINESS
description: 'Offer is invalid. Listing {listingId} currently has a seller-initiated negotiation.'
'150020':
domain: API_NEGOTIATION
category: BUSINESS
description: 'Listing {listingId} has no interested buyers.'
'150021':
domain: API_NEGOTIATION
category: BUSINESS
description: Seller initiating the offer is not active.
'150022':
domain: API_NEGOTIATION
category: BUSINESS
description: Offer is invalid. Maximum allowed offer limit reached.
'150023':
domain: API_NEGOTIATION
category: BUSINESS
description: Offer is invalid. Seller has exceeded their seller-initiated offer limit.
'150024':
domain: API_NEGOTIATION
category: BUSINESS
description: Offer is invalid. Items are listed on different sites.
'150025':
domain: API_NEGOTIATION
category: BUSINESS
description: 'Offer is invalid. {additionalInfo}'
'150026':
domain: API_NEGOTIATION
category: BUSINESS
description: 'Listing ID {listingId} is invalid, sellers cannot initiate an offer to a buyer for a Motors listing.'
'500':
description: Internal Server Error
x-response-codes:
errors:
'150000':
domain: API_NEGOTIATION
category: APPLICATION
description: 'Internal error. Please try the call again after a minute or two. If the error persists, contact eBay developer support for assistance.'
security:
- api_auth:
- 'https://api.ebay.com/oauth/api_scope/sell.inventory'
components:
schemas:
Amount:
type: object
properties:
currency:
type: string
description: 'The base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD. Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/sell/negotiation/types/bas:CurrencyCodeEnum''>eBay API documentation</a>'
value:
type: string
description: The monetary amount in the specified currency.
description: A complex type that describes the value of a monetary amount as represented by a global currency.
CreateOffersRequest:
type: object
properties:
allowCounterOffer:
type: boolean
description: 'If set to true, the buyer is allowed to make a counter-offer to the seller''s offer. Note: Currently, you must set this field to false; counter-offers are not supported in this release. Default: false'
message:
type: string
description: 'A seller-defined message related to the offer being made. This message is sent to the list of "interested" buyers. To increase the conversion rate of the offers a seller makes to buyers, eBay recommends you always add a customized message to your offers. Maximum length: 2,000 characters'
offerDuration:
description: 'The length of time the offer is valid from when it is created. The duration of the offer begins at the date and time denoted by creationDate. When the span of time specified by offerDuration passes beyond the creationDate, the offer expires. Note: offerDuration currently defaults to 2 days and you cannot set it to any other value (if specified, the unit and value fields in TimeDuration must be set to DAY and 2, respectively). Default: 2 Days'
$ref: '#/components/schemas/TimeDuration'
offeredItems:
type: array
description: 'An array of objects where each object contains the details of an offer and the ID of the listing on which the offer is being made. Note that the service does not currently support the creation of multiple offers with a single call to sendOfferToInterestedBuyer. With this, each request can target only one listing at a time and you must populate this array with a single element that contains the details of one offer.'
items:
$ref: '#/components/schemas/OfferedItem'
description: This complex type contains the fields needed to create an offer to a buyer that is initiated by the seller.
EligibleItem:
type: object
properties:
listingId:
type: string
description: The unique eBay-assigned ID for an eBay listing. A listingId is assigned by eBay when a seller creates a listing with the Trading API.
description: 'A listing that is eligible for a seller-initiated offer to a buyer. Listings are identified by a listingId value that is generated and assigned by eBay when a seller lists an item using the Trading API. Note: The Negotiation API does not currently support listings that are managed with the Inventory API.'
Error:
type: object
properties:
category:
type: string
description: Identifies the type of erro.
domain:
type: string
description: Name for the primary system where the error occurred. This is relevant for application errors.
errorId:
type: integer
description: A unique number to identify the error.
format: int32
inputRefIds:
type: array
description: An array of request elements most closely associated to the error.
items:
type: string
longMessage:
type: string
description: A more detailed explanation of the error.
message:
type: string
description: 'Information on how to correct the problem, in the end user''s terms and language where applicable.'
outputRefIds:
type: array
description: An array of request elements most closely associated to the error.
items:
type: string
parameters:
type: array
description: An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.
items:
$ref: '#/components/schemas/ErrorParameter'
subdomain:
type: string
description: 'Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc.'
description: This type defines the fields that can be returned in an error.
ErrorParameter:
type: object
properties:
name:
type: string
description: The object of the error.
value:
type: string
description: The value of the object.
Offer:
type: object
properties:
allowCounterOffer:
type: boolean
description: 'If set to true, the buyer is allowed to make a counter-offer to the seller''s offer.'
buyer:
description: The buyer who has been sent the offer.
$ref: '#/components/schemas/User'
creationDate:
type: string
description: 'The date and time when the seller''s offer was created. The returned timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z Example: 2018-08-20T07:09:00.000Z'
initiatedBy:
type: string
description: The eBay UserName of the user (seller) who initiated the offer.
lastModifiedDate:
type: string
description: The date and time when the offer was last modified. The returned timestamp is formatted as an ISO 8601 string.
message:
type: string
description: A seller-defined message related to the offer being made. This message is sent to the list of "interested" buyers along with the offer message from eBay.
offerDuration:
description: 'The length of time that the offer is valid. The duration of the offer begins at the date and time denoted by creationDate. When the span of time specified by offerDuration passes beyond the creationDate, the offer expires.'
$ref: '#/components/schemas/TimeDuration'
offeredItems:
type: array
description: 'The list of items associated with the offer. Currently, the offer list is restricted to a single offer.'
items:
$ref: '#/components/schemas/OfferedItem'
offerId:
type: string
description: A unique eBay-assigned identifier for the offer.
offerStatus:
type: string
description: 'The current state, or status, of an offer. Status states include PENDING, COUNTERED, ACCEPTED, and DECLINED. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/sell/negotiation/types/api:OfferStatusEnum''>eBay API documentation</a>'
offerType:
type: string
description: 'The type of offer being made. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/sell/negotiation/types/api:OfferTypeEnum''>eBay API documentation</a>'
revision:
type: string
description: 'A unique, eBay-assigned ID for the revision of the offer.'
description: A complex type that defines an offer that a seller makes to eligible buyers.
OfferedItem:
type: object
properties:
discountPercentage:
type: string
description: 'This value denotes the percentage that the listing in the offer will be discounted from its original listed price. The seller can specify either the exact price of the discounted items with the price field or they can use this field to specify the percentage that the listing will be discounted, but not both. Minimum: 5 Required if you do not specify a price value.'
listingId:
type: string
description: This value is a unique eBay-assigned ID that identifies the listing to which the offer pertains. A listingId value is generated by eBay when you list an item with the Trading API.
price:
description: 'This value denotes the final discounted price of the listing in the offer being made to the buyer. This value must be lower than the original price of the item as stated in the original listing. The seller can use either this field to specify the exact discounted price of the listing or they can use the discountPercentage field to specify the percentage that the listing will be discounted, but not both. Required if you do not specify a discountPercentage value.'
$ref: '#/components/schemas/Amount'
quantity:
type: integer
description: 'This integer value indicates the number of items in the eBay listing for which the offer is being made. The offer being made by the seller is an "all or nothing" offer, meaning the buyer must purchase the indicated quantity of items in order to receive the discount on the transaction. Default: 1'
format: int32
description: A complex type that defines the offer being made to an "interested" buyer.
PagedEligibleItemCollection:
type: object
properties:
eligibleItems:
type: array
description: A list of items that are eligible for a seller-initiated offer to a buyer. Each element in the list contains the listing ID of a listed item. These IDs represent the listings for which buyers have shown an interest.
items:
$ref: '#/components/schemas/EligibleItem'
href:
type: string
description: The URI of the current page of results from the result set.
limit:
type: integer
description: The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.
format: int32
next:
type: string
description: 'The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set. Max length: 2048'
offset:
type: integer
description: 'The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.'
format: int32
prev:
type: string
description: 'The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set. Max length: 2048'
total:
type: integer
description: 'The total number of items retrieved in the result set. If no items match the search criteria, the server returns the HTTP status code 204 No Content.'
format: int32
description: This complex type defines a collection of listings that are eligible for an offer to a buyer.
SendOfferToInterestedBuyersCollectionResponse:
type: object
properties:
offers:
type: array
description: The offers container returns a list of the offers sent to buyers who have shown an interest in listings included in the offer.
items:
$ref: '#/components/schemas/Offer'
description: The response object returned from a SendOfferToInterestedBuyers request.
TimeDuration:
type: object
properties:
unit:
type: string
description: 'A time-measurement unit that specifies a singular period of time. A span of time is defined when you apply the value specified in the value field to the value specified for unit. Time-measurement units can be YEAR, MONTH, DAY, and so on. See TimeDurationUnitEnum for a complete list of possible time-measurement units. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/sell/negotiation/types/bas:TimeDurationUnitEnum''>eBay API documentation</a>'
value:
type: integer
description: 'An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.'
format: int32
description: A complex type that specifies a period of time using a specified time-measurement unit.
User:
type: object
properties:
maskedUsername:
type: string
description: The masked user name is a user name that has certain characters hidden for privacy of the user.
description: This complex type identifies an eBay user.
securitySchemes:
api_auth:
type: oauth2
description: The security definitions for this API. Please check individual operations for applicable scopes.
flows:
authorizationCode:
authorizationUrl: 'https://auth.ebay.com/oauth2/authorize'
tokenUrl: 'https://api.ebay.com/identity/v1/oauth2/token'
scopes:
'https://api.ebay.com/oauth/api_scope/sell.inventory': View and manage your inventory and offers
'https://api.ebay.com/oauth/api_scope/sell.inventory.readonly': View your inventory and offers