negotiation APIv1.1.0

sendOfferToInterestedBuyers

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 (production)

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

URI parameters

HTTP request headers

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

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

Input container/fieldTypeDescription
allowCounterOfferbooleanIf 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

messagestringA 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

offerDurationTimeDurationThe 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.unitTimeDurationUnitEnumA 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.valueintegerAn integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Required

offeredItemsarray of OfferedItemAn 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.discountPercentagestringThis 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.listingIdstringThis 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.priceAmountThis 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.currencyCurrencyCodeEnumThe 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.valuestringThe monetary amount in the specified currency.

Occurrence: Required

offeredItems.quantityintegerThis 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

Output container/fieldTypeDescription
offersarray of OfferThe 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.allowCounterOfferbooleanIf set to true, the buyer is allowed to make a counter-offer to the seller's offer.

Occurrence: Always

offers.buyerUserThe buyer who has been sent the offer.

Occurrence: Always

offers.buyer.maskedUsernamestringThe masked user name is a user name that has certain characters hidden for privacy of the user.

Occurrence: Always

offers.creationDatestringThe 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.initiatedBystringThe eBay UserName of the user (seller) who initiated the offer.

Occurrence: Always

offers.lastModifiedDatestringThe date and time when the offer was last modified.

The returned timestamp is formatted as an ISO 8601 string.

Occurrence: Always

offers.messagestringA 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.offerDurationTimeDurationThe 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.unitTimeDurationUnitEnumA 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.valueintegerAn integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Always

offers.offeredItemsarray of OfferedItemThe list of items associated with the offer.

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

Occurrence: Always

offers.offeredItems.discountPercentagestringThis 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.listingIdstringThis 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.priceAmountThis 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.currencyCurrencyCodeEnumThe 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.valuestringThe monetary amount in the specified currency.

Occurrence: Conditional

offers.offeredItems.quantityintegerThis 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.offerIdstringA unique eBay-assigned identifier for the offer.

Occurrence: Always

offers.offerStatusOfferStatusEnumThe current state, or status, of an offer.

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

Occurrence: Always

offers.offerTypeOfferTypeEnumThe type of offer being made.

Occurrence: Always

offers.revisionstringA 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

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.
POST
https://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.