Skip to main content

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.

HeaderTypeDescription
Content-TypestringThis 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-IDstringThe 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

Request fields

Input container/fieldTypeDescription
allowCounterOfferboolean

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

messagestring

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

offerDurationTimeDuration

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.unitTimeDurationUnitEnum

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.valueinteger

An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Required

offeredItemsarray 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.discountPercentagestring

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.listingIdstring

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.priceAmount

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.currencyCurrencyCodeEnum

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.valuestring

The monetary amount in the specified currency.

Occurrence: Required

offeredItems.quantityinteger

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

Response fields

Output container/fieldTypeDescription
offersarray 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.allowCounterOfferboolean

If set to true, the buyer is allowed to make a counter-offer to the seller's offer.

Occurrence: Always

offers.buyerUser

The buyer who has been sent the offer.

Occurrence: Always

offers.buyer.maskedUsernamestring

The masked user name is a user name that has certain characters hidden for privacy of the user.

Occurrence: Always

offers.creationDatestring

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.initiatedBystring

The eBay UserName of the user (seller) who initiated the offer.

Occurrence: Always

offers.lastModifiedDatestring

The date and time when the offer was last modified.

The returned timestamp is formatted as an ISO 8601 string.

Occurrence: Always

offers.messagestring

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.offerDurationTimeDuration

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.unitTimeDurationUnitEnum

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.valueinteger

An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Always

offers.offeredItemsarray of OfferedItem

The list of items associated with the offer.

Currently, the offer list is restricted to a single offer.

Occurrence: Always

offers.offeredItems.discountPercentagestring

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.listingIdstring

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.priceAmount

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.currencyCurrencyCodeEnum

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.valuestring

The monetary amount in the specified currency.

Occurrence: Conditional

offers.offeredItems.quantityinteger

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.offerIdstring

A unique eBay-assigned identifier for the offer.

Occurrence: Always

offers.offerStatusOfferStatusEnum

The current state, or status, of an offer.

Status states include PENDING, COUNTERED, ACCEPTED, and DECLINED.

Occurrence: Always

offers.offerTypeOfferTypeEnum

The type of offer being made.

Occurrence: Always

offers.revisionstring

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.

StatusMeaning
200Success
400Bad Request
409Conflict
500Internal Server Error

Error codes

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

CodeDomainCategoryMeaning
150000API_NEGOTIATIONAPPLICATIONInternal error. Please try the call again after a minute or two. If the error persists, contact eBay developer support for assistance.
150001API_NEGOTIATIONREQUESTMandatory headers are missing.
150002API_NEGOTIATIONREQUESTThe marketplace value {marketplaceId} is not supported. The supported values are: {marketplaceIds}
150005API_NEGOTIATIONREQUESTOffer contains multiple listings {listingIds}.
150006API_NEGOTIATIONREQUESTRequest cannot be null/empty.
150007API_NEGOTIATIONREQUESTBoth offer price and discount percentage cannot be present in the request.
150008API_NEGOTIATIONREQUESTPrice must be at least {minPercentageDifference} less than your Buy It Now price.
150009API_NEGOTIATIONREQUESTInvalid value for {fieldName}. {additionalInfo}
150010API_NEGOTIATIONBUSINESSInvalid message. Message cannot contain HTML or blocked words and cannot exceed maximum character limit of 2000.
150011API_NEGOTIATIONBUSINESSInvalid listingId {listingId}. The listing for this offer has ended.
150012API_NEGOTIATIONBUSINESSInvalid listingId {listingId}. No such listing for this seller.
150013API_NEGOTIATIONBUSINESSInvalid listingId {listingId}. {additionalInfo}
150014API_NEGOTIATIONBUSINESSCurrent available quantity for this listing {listingId} is less than the offer quantity.
150015API_NEGOTIATIONBUSINESSInvalid price for listing {listingId}. Minimum offer price of {minPrice} not met.
150016API_NEGOTIATIONBUSINESSInvalid price for listing {listingId}. Price value exceeds the listing price.
150017API_NEGOTIATIONBUSINESSListing {listingId} does not support offer.
150018API_NEGOTIATIONBUSINESSOffer is invalid. A best offer currently exists on the listing {listingId}.
150019API_NEGOTIATIONBUSINESSOffer is invalid. Listing {listingId} currently has a seller-initiated negotiation.
150020API_NEGOTIATIONBUSINESSListing {listingId} has no interested buyers.
150021API_NEGOTIATIONBUSINESSSeller initiating the offer is not active.
150022API_NEGOTIATIONBUSINESSOffer is invalid. Maximum allowed offer limit reached.
150023API_NEGOTIATIONBUSINESSOffer is invalid. Seller has exceeded their seller-initiated offer limit.
150024API_NEGOTIATIONBUSINESSOffer is invalid. Items are listed on different sites.
150025API_NEGOTIATIONBUSINESSOffer is invalid. {additionalInfo}
150026API_NEGOTIATIONBUSINESSListing ID {listingId} is invalid, sellers cannot initiate an offer to a buyer for a Motors listing.
150027API_NEGOTIATIONREQUESTOffer 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.