Sellers can use the Negotiation API to send discount offers to buyers who have shown an interest in their eBay listings. By sending interested buyers offers to purchase their items at a discount, sellers can use the API to increase the velocity of their item sales.
Buyers can show interest in a listing in a variety of ways. For example, a buyer is deemed to have shown interest in a listing when they add the listing to their Watch list, or if they add the listing to their shopping cart and later abandon the cart. When buyers show an interest in a listing, they become eligible to receive discount offers on the listing from the seller.
Finding listings with interested buyers
Sellers use the findEligibleItems method to discover which of their listings have "interested" buyers.
This method does not use a request payload. Just set the X-EBAY-C-MARKETPLACE-ID header to the marketplace you want to search, then make the call using the following endpoint:
GET https://api.ebay.com/sell/negotiation/v1/find_eligible_items
This call returns a simple set of current listing IDs, where at least one buyer has shown an interest in each ID returned.
The result set is paginated because a request can return a large number of listing IDs. Control the pagination of the response using the limit and offset query parameters.
Sending offers to buyers
With a set of eligible listings in hand, sellers can call sendOfferToInterestedBuyers to—as one might expect—send an offer to the buyers who have shown an interest in a listing.
The sendOfferToInterestedBuyers request
This request requires a bit more setup than does findEligibleItems. Configure your request to sendOfferToInterestedBuyers as shown in the following sample call:
{
"message": "This is an offer!", // The seller's message to the buyer
"offeredItems": [ // The details of the offer
{
"price": { // Specify a new discounted price OR
"value": "8.95", // the percent discounted off the listed price
"currency": "USD"
},
"quantity": "1", // The number of items that must be purchased
// to activate the discount
"listingId": "270010067293" // The ID of the listing on which the offer is made
}
],
"offerDuration": { // The length of time for which the offer is valid,
"unit": "DAY", // starting when the offer is created
"value": "2"
}
}
The response from this request contains a list of the offers that were made as a result of the request. Each element in the list contains the details and status of the offer, plus the buyer to whom the offer was extended.
eBay sends a notification to each buyer listed in the response. Each notification contains the details the offer being made, including any seller-supplied message.
The sendOfferToInterestedBuyers response
When you call sendOfferToInterestedBuyers, a notification message is sent to every eligible buyer who has shown interest in the itemId specified in the request.
In response to the call, the service returns a list of offers, where each element in the list contains the details of an offer that was sent.
Among other details, of each offer contain the offer's creationDate and offerDuration. The buyer to whom the offer was sent is also contained in the response, although the buyer's name is masked in all seller-initiated offers.
The following example shows an offer where the discount is a percentage off the initial listing price:
{
"offers":[
{
"offerId": "*5003605016",
"revision": "5003605016",
"message": "This is an offer!",
"buyer": {
"maskedUsername": "7****s"
},
"creationDate": "2019-08-21T22:24:25.305Z",
"lastModifiedDate": "2019-08-21T22:24:25.305Z",
"offerDuration": {
"value": 2,
"unit": "DAY"
},
"offerStatus": "PENDING",
"initiatedBy": "raja_sio",
"offeredItems": [
{
"listingId": "330012131478",
"quantity": 1,
"discountPercentage": "10"
}
],
"allowCounterOffer": false,
"offerType": "SELLER_INITIATED_OFFER"
}
]
}
Log into your eBay account and navigate to Seller Hub to monitor and manage the offers you've sent. When you click into one of the items for which you have extended an offer to buyers, a header with a Manage Offers link is displayed. Click the link to view and manage the offers created for that item ID.
Testing in the Sandbox
Testing a complete end-to-end Negotiation API transaction requires both seller and buyer interactions.
The process begins when a seller makes an offer and continues when the buyer either accepts or rejects the offer using eBay web flows. In the Sandbox, the buyer flow begins in the Sandbox UI.
These buyer and seller flows are supported in the Sandbox environment; however, some call-specific considerations must be kept in mind when you're testing.
Sandbox considerations for findEligibleItems
In the real world, buyers show interest in a listing by either adding the listing to their Watch list, or by adding the listing to their shopping cart and later abandon the cart. By showing interest, buyers become "eligible" to receive offers from the seller.
Because the Sandbox does not track "eligible" buyers, findEligibleItems returns a set of IDs that consists of the active listingId values from the seller’s recently created items in the Sandbox. The listing IDs returned are sorted in descending order by creation date. It then follows that findEligibleItems does not validate whether or not there are "eligible" buyers associated with the listing IDs returned in the Sandbox.
Note that the Sandbox can return IDs for listings that are posted in a marketplace that is not supported by the Negotiation API (meaning you will get an error if you try to pass such a listing ID on to sendOfferToInterestedBuyers).
To add, findEligibleItems can return Sandbox listings IDs that reference multi-variation listings. These are listings for which you cannot create an offer to a buyer, and you will receive an error if you attempt to pass a multi-variation listing ID to findEligibleItems (note that in the Production environment, findEligibleItems does not return multi-SKU listing IDs).
Also consider, a call to findEligibleItems in the Sandbox might return item IDs for which you have existing offers (an action that does not occur in Production). You will get an error if you attempt to call sendOfferToInterestedBuyers using an item ID that is associated with existing offers.
Sandbox considerations for sendOfferToInterestedBuyers
Because findEligibleItems does not create a list of real (or even virtual) "eligible" Sandbox buyers, sendOfferToInterestedBuyers cannot send notifications to the list of buyers who are interested in the IDs returned by findEligibleItems.
Instead, sendOfferToInterestedBuyers sends notifications to a random set of Sandbox "buyers." The buyers are picked from a pool of mock Sandbox TESTUSER accounts, and their buyer names are masked and returned in the response to your sendOfferToInterestedBuyers request.
Lastly, a call to sendOfferToInterestedBuyers in the Sandbox returns a maximum of 10 offers, where each offer is "sent" to one of the mock Sandbox accounts. The offerId values returned by the Sandbox service are factitious.