GetBestOffers

Use this call to retrieve details of Best Offers for items being sold by or being bid on by the user. Offers are selected for return based on the BestOfferStatus filter (Active by default). See Enabling Best Offer for details.

Usage Details

Options:

• If you have the BestOfferID value, you can submit this value along with its associated ItemID to get details about that Best Offer.
• If you provide just an ItemID (and omit BestOfferID), you receive a list of IDs of all Best Offers for that ItemID (filtered per BestOfferStatus).
• If you omit both ItemID and BestOfferID, you receive a list of IDs of all active Best Offers related to the calling user--up to 1,000 IDs for Best Offers the user submitted as a bidder and up to 10,000 IDs for Best Offers the user received as a seller.

Note the following rules and restrictions to the use of GetBestOffers:

• If the seller retrieves the Best Offer details for a listing--The seller sees the offer price and currency of each Best Offer, whether the listing is active or has ended. The seller sees email ids only for those users whose Best Offers have been accepted.
• If a bidder retrieves the Best Offer details for a listing--The bidder sees his own Best Offer and the current state of whichever offer is currently the Best Offer (for example, whether or not the seller has made a counter offer).
• If a non-winning bidder makes the call for a listing--If the listing has not ended, he sees the offer price and currency he submitted in his offer. If the listing has ended, he sees everyone's offer prices and currencies. He sees no email ids.
• If a winning bidder makes the call for a listing--If the listing has not ended, he sees the offer price and currency he submitted in his offer. If the listing has ended, he sees everyone's offer prices and currencies. He sees his own email id but no others.
• If the user is neither the seller nor a bidder for a listing--The user sees all offer prices and currencies of all bidders IF the listing has ended. Otherwise, the user sees nothing. No email ids are returned.

For more information on when email addresses are returned, see Email and Address Privacy Policy.

Testing GetBestOffers

To test GetBestOffers in the Sandbox environment, you need at least two test users---one to act as the seller, the other as the bidder.

1. List an item using the seller test user. Create a FixedPriceItem and enable Item.BestOfferDetails.BestOfferEnabled.
2. Have other test user submit an offer on the item using PlaceOffer. You can also use the Sandbox UI (http://sandbox.ebay.com) to place the offer.
3. Call GetBestOffers as one of the two users, providing no ItemID or BestOfferID. You should see a list of IDs of Best Offers related to this user.
4. Call GetBestOffers as one of the two users, providing ItemID but no BestOfferID. You should see a list of IDs of Best Offers related to that listing.

Related Information

See:
    Best Offer
    User information

Input

See also Samples.

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.

The XML prototype does not include requester credentials. This is a documentation limitation only (see Standard Requester Credentials for Making Calls).

<?xml version="1.0" encoding="utf-8"?>
<GetBestOffersRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Input Fields -->
  <BestOfferID> BestOfferIDType (string) </BestOfferID>
  <BestOfferStatus> BestOfferStatusCodeType </BestOfferStatus>
  <ItemID> ItemIDType (string) </ItemID>
  <Pagination> PaginationType
    <EntriesPerPage> int </EntriesPerPage>
    <PageNumber> int </PageNumber>
  </Pagination>
  <!-- Standard Input Fields -->
  <DetailLevel> DetailLevelCodeType </DetailLevel>
  <!-- ... more DetailLevel values allowed here ... -->
  <ErrorLanguage> string </ErrorLanguage>
  <MessageID> string </MessageID>
  <OutputSelector> string </OutputSelector>
  <!-- ... more OutputSelector values allowed here ... -->
  <Version> string </Version>
  <WarningLevel> WarningLevelCodeType </WarningLevel>
</GetBestOffersRequest>

 If the following output selectors are used: 

...
 <OutputSelector>ViewItemURL</OutputSelector>
 <OutputSelector>BuyItNowPrice</OutputSelector> 
... 

 ...the response might look like the following 

  <Item>
 <BuyItNowPrice currencyID="USD">0.0</BuyItNowPrice>
 <ListingDetails>
 <ViewItemURL>http://www.ebay.com/itm/Tag-Heuer-Mens-Watch/182879833261</ViewItemURL>
 </ListingDetails>
 </Item>  

Output

See also Samples.

The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are not returned (or soon will not be returned) or are not operational (or soon will be non-operational).

<?xml version="1.0" encoding="utf-8"?>
<GetBestOffersResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Output Fields -->
  <BestOfferArray> BestOfferArrayType
    <BestOffer> BestOfferType
      <BestOfferCodeType> BestOfferTypeCodeType </BestOfferCodeType>
      <BestOfferID> BestOfferIDType (string) </BestOfferID>
      <Buyer> UserType
        <Email> string </Email>
        <FeedbackScore> int </FeedbackScore>
        <RegistrationDate> dateTime </RegistrationDate>
        <ShippingAddress> AddressType </ShippingAddress>
        <UserID> UserIDType (string) </UserID>
      </Buyer>
      <BuyerMessage> string </BuyerMessage>
      <ExpirationTime> dateTime </ExpirationTime>
      <Price currencyID="CurrencyCodeType"> AmountType (double) </Price>
      <Quantity> int </Quantity>
      <SellerMessage> string </SellerMessage>
      <Status> BestOfferStatusCodeType </Status>
    </BestOffer>
    <!-- ... more BestOffer nodes allowed here ... -->
  </BestOfferArray>
  <Item> ItemType
    <BuyItNowPrice currencyID="CurrencyCodeType"> AmountType (double) </BuyItNowPrice>
    <Currency> CurrencyCodeType </Currency>
    <ItemID> ItemIDType (string) </ItemID>
    <ListingDetails> ListingDetailsType
      <EndTime> dateTime </EndTime>
    </ListingDetails>
  </Item>
  <ItemBestOffersArray> ItemBestOffersArrayType
    <ItemBestOffers> ItemBestOffersType
      <BestOfferArray> BestOfferArrayType
        <BestOffer> BestOfferType
          <BestOfferCodeType> BestOfferTypeCodeType </BestOfferCodeType>
          <BestOfferID> BestOfferIDType (string) </BestOfferID>
          <Buyer> UserType
            <Email> string </Email>
            <FeedbackScore> int </FeedbackScore>
            <RegistrationDate> dateTime </RegistrationDate>
            <ShippingAddress> AddressType </ShippingAddress>
            <UserID> UserIDType (string) </UserID>
          </Buyer>
          <BuyerMessage> string </BuyerMessage>
          <ExpirationTime> dateTime </ExpirationTime>
          <Price currencyID="CurrencyCodeType"> AmountType (double) </Price>
          <Quantity> int </Quantity>
          <SellerMessage> string </SellerMessage>
          <Status> BestOfferStatusCodeType </Status>
        </BestOffer>
        <!-- ... more BestOffer nodes allowed here ... -->
      </BestOfferArray>
      <Item> ItemType
        <BuyItNowPrice currencyID="CurrencyCodeType"> AmountType (double) </BuyItNowPrice>
        <Currency> CurrencyCodeType </Currency>
        <ItemID> ItemIDType (string) </ItemID>
        <ListingDetails> ListingDetailsType
          <EndTime> dateTime </EndTime>
        </ListingDetails>
      </Item>
      <Role> TradingRoleCodeType </Role>
    </ItemBestOffers>
    <!-- ... more ItemBestOffers nodes allowed here ... -->
  </ItemBestOffersArray>
  <PageNumber> int </PageNumber>
  <PaginationResult> PaginationResultType
    <TotalNumberOfEntries> int </TotalNumberOfEntries>
    <TotalNumberOfPages> int </TotalNumberOfPages>
  </PaginationResult>
  <!-- Standard Output Fields -->
  <Ack> AckCodeType </Ack>
  <Build> string </Build>
  <CorrelationID> string </CorrelationID>
  <Errors> ErrorType
    <ErrorClassification> ErrorClassificationCodeType </ErrorClassification>
    <ErrorCode> token </ErrorCode>
    <ErrorParameters ParamID="string"> ErrorParameterType
      <Value> string </Value>
    </ErrorParameters>
    <!-- ... more ErrorParameters nodes allowed here ... -->
    <LongMessage> string </LongMessage>
    <SeverityCode> SeverityCodeType </SeverityCode>
    <ShortMessage> string </ShortMessage>
  </Errors>
  <!-- ... more Errors nodes allowed here ... -->
  <HardExpirationWarning> string </HardExpirationWarning>
  <Timestamp> dateTime </Timestamp>
  <Version> string </Version>
</GetBestOffersResponse>

Detail Controls

DetailLevel

The DetailLevel input field influences which call-specific fields may be returned. (All standard output fields are returned regardless of DetailLevel.)

The none column indicates the fields that are returned when you do not specify a DetailLevel.

Samples

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

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Returns all the best offers made for a particular ItemID.

Description

The following call queries for all best offers made for a particular ItemID. DetailLevel is set to ReturnAll, which causes the response to include all messages from prospective buyers, if they exist.

Input

XML format.

<?xml version="1.0" encoding="utf-8"?>
<GetBestOffersRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
    <eBayAuthToken>A*******3</eBayAuthToken>
  </RequesterCredentials>
  <ItemID>7**********0</ItemID>
  <DetailLevel>ReturnAll</DetailLevel>
  <BestOfferStatus>All</BestOfferStatus>
</GetBestOffersRequest>

Output

XML format.
<?xml version="1.0" encoding="UTF-8" ?>
<GetBestOffersResponse xmlns="urn:ebay:apis:eBLBaseComponents">
<Timestamp>2019-11-04T18:01:14.906Z</Timestamp>
<Ack>Success</Ack>
<Version>1125</Version>
<Build>E1125_CORE_API_19070409_R1</Build>
<BestOfferArray>
  <BestOffer>
    <BestOfferID>2*****7</BestOfferID>
    <ExpirationTime>2019-11-05T18:01:14.906Z</ExpirationTime>
    <Buyer>
      <Email>b********@*****.com</Email>
      <FeedbackScore>500</FeedbackScore>
      <RegistrationDate>1995-01-01T00:00:00.000Z</RegistrationDate>
      <UserID>t********r</UserID>
    </Buyer>
    <Price currencyID="USD">15.0</Price>
    <Status>Pending</Status>
    <Quantity>1</Quantity>
    <BestOfferCodeType>BuyerBestOffer</BestOfferCodeType>
  </BestOffer>
  <BestOffer>
    <BestOfferID>2*****6</BestOfferID>
    <ExpirationTime>2019-11-05T18:01:14.906Z</ExpirationTime>
    <Buyer>
      <Email>t********@*****.com</Email>
      <FeedbackScore>1</FeedbackScore>
      <RegistrationDate>2004-02-05T00:00:00.000Z</RegistrationDate>
      <UserID>t********r</UserID>
    </Buyer>
    <Price currencyID="USD">14.0</Price>
    <Status>Pending</Status>
    <Quantity>1</Quantity>
    <BestOfferCodeType>BuyerBestOffer</BestOfferCodeType>
  </BestOffer>
  </BestOfferArray>
  <Item>
    <BuyItNowPrice currencyID="USD">23.0</BuyItNowPrice>
    <ListingDetails>
      <EndTime>2019-11-14T18:01:14.906Z</EndTime>
    </ListingDetails>
    <Location>Seattle, WA</Location>
    <Title>Wizard Outfit</Title>
  </Item>
</GetBestOffersResponse>

Change History