sendOfferToInterestedBuyers: eBay Negotiation API

POST/send_offer_to_interested_buyers

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.

Input

Resource URI

POST https://api.ebay.com/sell/negotiation/v1/send_offer_to_interested_buyers

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

This method has no URI parameters.

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

Header	Type	Description
Content-Type	string	This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required
X-EBAY-C-MARKETPLACE-ID	string	The eBay marketplace on which your listings with "eligible" buyers appear. For a complete list of supported marketplaces, see Negotiation API requirements and restrictions. Occurrence: Required

Header

Type

Description

Content-Type

string

This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

X-EBAY-C-MARKETPLACE-ID

string

The eBay marketplace on which your listings with "eligible" buyers appear.

For a complete list of supported marketplaces, see Negotiation API requirements and restrictions.

Occurrence: Required

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.inventory

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

{ /* CreateOffersRequest */

"allowCounterOffer" : "boolean",

"message" : "string",

"offerDuration" :

{ /* TimeDuration */

"unit" : "TimeDurationUnitEnum : [YEAR,MONTH,DAY...]",

"value" : "integer"

"offeredItems" : [

{ /* OfferedItem */

"discountPercentage" : "string",

"listingId" : "string",

"price" :

{ /* Amount */

"currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",

"value" : "string"

"quantity" : "integer"

}

]

}

Request fields

Input container/field	Type	Description
allowCounterOffer	boolean	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` Occurrence: Optional
message	string	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 Occurrence: Optional
offerDuration	TimeDuration	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 Occurrence: Optional
offerDuration.unit	TimeDurationUnitEnum	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. Occurrence: Required
offerDuration.value	integer	An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field. Occurrence: Required
offeredItems	array of OfferedItem	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. Occurrence: Required
offeredItems.discountPercentage	string	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. Occurrence: Conditional
offeredItems.listingId	string	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. Occurrence: Required
offeredItems.price	Amount	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. Occurrence: Conditional
offeredItems.price.currency	CurrencyCodeEnum	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. Occurrence: Optional
offeredItems.price.value	string	The monetary amount in the specified currency. Occurrence: Required
offeredItems.quantity	integer	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` Occurrence: Optional

Output

HTTP response headers

This call has no response headers.

Response payload

Copy complete valid JSON to clipboard

{ /* SendOfferToInterestedBuyersCollectionResponse */

"offers" : [

{ /* Offer */

"allowCounterOffer" : "boolean",

"buyer" :

{ /* User */

"maskedUsername" : "string"

"creationDate" : "string",

"initiatedBy" : "string",

"lastModifiedDate" : "string",

"message" : "string",

"offerDuration" :

{ /* TimeDuration */

"unit" : "TimeDurationUnitEnum : [YEAR,MONTH,DAY...]",

"value" : "integer"

"offeredItems" : [

{ /* OfferedItem */

"discountPercentage" : "string",

"listingId" : "string",

"price" :

{ /* Amount */

"currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",

"value" : "string"

"quantity" : "integer"

}

"offerId" : "string",

"offerStatus" : "OfferStatusEnum : [PENDING,RETRACTED,EXPIRED...]",

"offerType" : "OfferTypeEnum : [SELLER_INITIATED_OFFER]",

"revision" : "string"

}

]

}

Response fields

Output container/field	Type	Description
offers	array of Offer	The offers container returns a list of the offers sent to buyers who have shown an interest in listings included in the offer. Occurrence: Always
offers.allowCounterOffer	boolean	If set to `true`, the buyer is allowed to make a counter-offer to the seller's offer. Occurrence: Always
offers.buyer	User	The buyer who has been sent the offer. Occurrence: Always
offers.buyer.maskedUsername	string	The masked user name is a user name that has certain characters hidden for privacy of the user. Occurrence: Always
offers.creationDate	string	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` Occurrence: Always
offers.initiatedBy	string	The eBay UserName of the user (seller) who initiated the offer. Occurrence: Always
offers.lastModifiedDate	string	The date and time when the offer was last modified. The returned timestamp is formatted as an ISO 8601 string. Occurrence: Always
offers.message	string	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. Occurrence: Conditional
offers.offerDuration	TimeDuration	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. Occurrence: Always
offers.offerDuration.unit	TimeDurationUnitEnum	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. Occurrence: Always
offers.offerDuration.value	integer	An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field. Occurrence: Always
offers.offeredItems	array of OfferedItem	The list of items associated with the offer. Currently, the offer list is restricted to a single offer. Occurrence: Always
offers.offeredItems.discountPercentage	string	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. Occurrence: Conditional
offers.offeredItems.listingId	string	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. Occurrence: Conditional
offers.offeredItems.price	Amount	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. Occurrence: Conditional
offers.offeredItems.price.currency	CurrencyCodeEnum	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. Occurrence: Conditional
offers.offeredItems.price.value	string	The monetary amount in the specified currency. Occurrence: Conditional
offers.offeredItems.quantity	integer	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` Occurrence: Conditional
offers.offerId	string	A unique eBay-assigned identifier for the offer. Occurrence: Always
offers.offerStatus	OfferStatusEnum	The current state, or status, of an offer. Status states include `PENDING`, `COUNTERED`, `ACCEPTED`, and `DECLINED`. Occurrence: Always
offers.offerType	OfferTypeEnum	The type of offer being made. Occurrence: Always
offers.revision	string	A unique, eBay-assigned ID for the revision of the offer. Occurrence: Always

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

Status	Meaning
200	Success
400	Bad Request
409	Conflict
500	Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

Code	Domain	Category	Meaning
150000	API_NEGOTIATION	APPLICATION	Internal error. Please try the call again after a minute or two. If the error persists, contact eBay developer support for assistance.
150001	API_NEGOTIATION	REQUEST	Mandatory headers are missing.
150002	API_NEGOTIATION	REQUEST	The marketplace value {marketplaceId} is not supported. The supported values are: {marketplaceIds}
150005	API_NEGOTIATION	REQUEST	Offer contains multiple listings {listingIds}.
150006	API_NEGOTIATION	REQUEST	Request cannot be null/empty.
150007	API_NEGOTIATION	REQUEST	Both offer price and discount percentage cannot be present in the request.
150008	API_NEGOTIATION	REQUEST	Price must be at least {minPercentageDifference} less than your Buy It Now price.
150009	API_NEGOTIATION	REQUEST	Invalid value for {fieldName}. {additionalInfo}
150010	API_NEGOTIATION	BUSINESS	Invalid message. Message cannot contain HTML or blocked words and cannot exceed maximum character limit of 2000.
150011	API_NEGOTIATION	BUSINESS	Invalid listingId {listingId}. The listing for this offer has ended.
150012	API_NEGOTIATION	BUSINESS	Invalid listingId {listingId}. No such listing for this seller.
150013	API_NEGOTIATION	BUSINESS	Invalid listingId {listingId}. {additionalInfo}
150014	API_NEGOTIATION	BUSINESS	Current available quantity for this listing {listingId} is less than the offer quantity.
150015	API_NEGOTIATION	BUSINESS	Invalid price for listing {listingId}. Minimum offer price of {minPrice} not met.
150016	API_NEGOTIATION	BUSINESS	Invalid price for listing {listingId}. Price value exceeds the listing price.
150017	API_NEGOTIATION	BUSINESS	Listing {listingId} does not support offer.
150018	API_NEGOTIATION	BUSINESS	Offer is invalid. A best offer currently exists on the listing {listingId}.
150019	API_NEGOTIATION	BUSINESS	Offer is invalid. Listing {listingId} currently has a seller-initiated negotiation.
150020	API_NEGOTIATION	BUSINESS	Listing {listingId} has no interested buyers.
150021	API_NEGOTIATION	BUSINESS	Seller initiating the offer is not active.
150022	API_NEGOTIATION	BUSINESS	Offer is invalid. Maximum allowed offer limit reached.
150023	API_NEGOTIATION	BUSINESS	Offer is invalid. Seller has exceeded their seller-initiated offer limit.
150024	API_NEGOTIATION	BUSINESS	Offer is invalid. Items are listed on different sites.
150025	API_NEGOTIATION	BUSINESS	Offer is invalid. {additionalInfo}
150026	API_NEGOTIATION	BUSINESS	Listing ID {listingId} is invalid, sellers cannot initiate an offer to a buyer for a Motors listing.
150027	API_NEGOTIATION	REQUEST	Offer is invalid. Please specify a valid duration of {durationValue} {durationUnit}

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Send a discount offer to interested buyers

This sample shows how to send an offer to all the buyers who have shown an interest in a seller's listing.

When you make this call, eBay sends each buyer who has shown an "interest" in the listing a message that details your offer, plus your personal offer message.

Input

In the request payload for this call, include:

The ID of the item that is being discounted.
A user-defined message that introduces the offer being made to the buyer.
The "duration" of the offer.
The amount of the discount being offered, either a percentage or monetary amount that is subtracted from the original listing price.
The quantity of the items that must be bought to receive the discount.

POSThttps://api.ebay.com/sell/negotiation/v1/send_offer_to_interested_buyers

Output

A successful call returns a list of the offers that were sent as a result of the request.

{  
  "offers":[  
    {  
      "offerId":"*5********6",
      "revision":"5********6",
      "message":"test",
      "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":"r********o",
      "offeredItems":[  
        {  
          "listingId":"3********8",
          "quantity":1,
          "discountPercentage":"10"
        }
      ],
      "allowCounterOffer":false,
      "offerType":"SELLER_INITIATED_OFFER"
    },
    {  
      "offerId":"*5********6",
      "revision":"5********6",
      "message":"test",
      "buyer":{  
        "maskedUsername":"s****b"
      },
      "creationDate":"2019-08-21T22:24:25.305Z",
      "lastModifiedDate":"2019-08-21T22:24:25.305Z",
      "offerDuration":{  
        "value":2,
        "unit":"DAY"
      },
      "offerStatus":"PENDING",
      "initiatedBy":"r********o",
      "offeredItems":[  
        {  
          "listingId":"3********8",
          "quantity":1,
          "discountPercentage":"10"
        }
      ],
      "allowCounterOffer":false,
      "offerType":"SELLER_INITIATED_OFFER"
    }
  ]
}