PlaceOffer

Use this call to place a bid or a Best Offer on a listing, or to make a purchase. Note that this call cannot be used to purchase items that require immediate payment.

Usage Details

In an auction listing with a Buy It Now option, PlaceOffer can be used to buy the item immediately, foregoing the bidding process.

PlaceOffer can be used to buy items from basic fixed-price listings. In this case, the call is used to purchase one or more items at the price in the listing. Use PlaceOffer to purchase as many items as desired from the listing, up to the total number in the listing. A single call can be made that enables a user to buy multiple items from the same listing. Alternatively, PlaceOffer can be called multiple times on the same listing, with each call purchasing a subset of the total number of items desired.

PlaceOffer can be used to make a Best Offer; for information about the Best Offer feature (including rules for counteroffers), see Enabling Best Offer.

In the PlaceOffer request, specify an ItemID. Use the Action field to specify if you want to make a Bid or Purchase. For more information about the possible input values for PlaceOffer (including about functionality related to best offer), see PlaceOffer Input.

PlaceOffer and Currencies

Offer.Currency and the CurrencyID attribute on Offer.MaxBid are ignored for PlaceOffer. The currency that will be used in the order line item is the currency specified by the seller when adding the item. However, your users may want to see current conversion rates before placing an offer. To let them check currency conversion rates send them to the xe.com Universal Currency Converter provided by eBay.

Global Shipping Program Compatibility

PlaceOffer is not compatible with eBay's Global Shipping Program prior to version 787. This means that when a buyer attempts to purchase an item that's listed with International Priority Shipping as an international shipping option and PlaceOffer is invoked, the buyer will receive an error message indicating that the item can be purchased only on one of the main eBay sites.

You must upgrade your application to version 787 or higher of the Trading API schema before attempting to call PlaceOffer to let buyers purchase Global Shipping Program-enabled items.

For more information about using the Global Shipping Program, see the Managing Shipping chapter of the Trading API User's Guide.

Applying for Approval of the eBay Partner Network

Use of PlaceOffer in production is only granted to those that pass the affiliate vetting process.

Note: eBay is no longer accepting applications.

PlaceOffer Policies and Guidelines

Partners approved by the eBay Partner Network are required to pass the eBay Developer Support review. You should reread the policies below because these must be followed, and you should also reread the guidelines (which contain practices that you should follow).

PlaceOffer Policies

The following PlaceOffer policies are required for applications that use this call in the production environment:

• Use of PlaceOffer must be in accordance with the API License Agreement and the eBay User Agreement. If you are an eBay affiliate, you must agree to all terms and conditions specific to the eBay programs you join.
• The automatic and/or scheduled use of PlaceOffer is prohibited. An example is sniping, which is prohibited. For each PlaceOffer call made by your application, the user first must take an explicit action. That is, the application needs to get confirmation from the user before making each PlaceOffer call.
• The application shall not in any way, shape, or form collect the eBay username and password values of buyers or sellers that are involved in order line items. Users must enable bidding and buying through eBay's Authentication & Authorization mechanisms.
• The "Right Now On eBay" logo may be part of your application and Web UI. The plain eBay logo cannot be used in any part of the application and Web UI without written consent from eBay, Inc. For more information on logo policies, see API Logo Usage Requirements.
• The name "eBay" cannot be in any part of your product name or web domain. For example, the following is not allowed: http://www.blahebay.com
• To use PlaceOffer in the production environment, you must apply for, and be granted, approval by the eBay Partner Network. Additionally, your application must be functional in the sandbox environment. Note: eBay is no longer accepting applications.

Please note the following policies regarding use of PlaceOffer in the production environment:

• After you apply for approval by the eBay Partner Network, and if it is granted, then you must pass an application review by eBay Developer Support.
• If you are an eBay affiliate, your eBay Partner Network account may be temporarily suspended during the review process if your business practices and/or product functionalities are deemed questionable by eBay.

PlaceOffer Guidelines

This section contains guidelines for PlaceOffer, which are designed to help developers deliver a more reliable shopping experience to eBay users:

• Please adopt the following bid flow to ensure bids are placed appropriately by the shopper:

  

• The user should see the following item information before placing their first bid or making a purchase:
  • Title
  • Description
  • Photo(s), if suitable for display screen
  • Current price and bidding information (i.e., reserve price status)
  • Seller ID and feedback score
  • Shipping information
  • Payment options

• You should also review the documentation for all PlaceOffer error codes and provide messaging as needed to the user when your application receives errors. See The Top Error Codes Returned for PlaceOffer

  Also, it is a good practice to account for the following types of errors:

  • Bid not above minimum
  • Auction has ended
  • User has been outbid
  • User attempts to lower previous bid
• Clearly label your application with the application name and the company name. Build information should be available through the Help.
• Use InvocationID to test if the PlaceOffer call succeeded. This is important if the application fails to get a response after making a call, due to network issues. If the same InvocationID is passed in after it has been passed in once on a call that succeeded, for a particular application and user, then an error is returned.
• For applications that offer status alerts for activities such as Outbid, please do not use GetItem for frequent item status checks. To check for status, use GetItemStatus in the Shopping API.
• For the best performance, use GetItemStatus to retrieve auction information. Your application should gradually increase polling frequency as the ending time approaches. Making three GetItemStatus API calls each minute during the last three minutes of an auction should be the maximum frequency.
• When passing in EndUserIP, use the client's external IP address (do NOT pass the private or LAN IP address).

• A BotBlock handle should be implemented wherever possible because eBay may ask users to respond to a CAPTCHA challenge from time to time. A BotBlock handle also can be treated as an error.

  To invoke a CAPTCHA challenge to test BotBlock, you can use GetChallengeToken.

Earning Affiliate Commissions with PlaceOffer

Affiliate-commission functionality is not available in the Sandbox environment. Affiliate commissions from PlaceOffer require that the call be made to the site on which the item is listed. Affiliate commissions from PlaceOffer also require that the affiliate has signed up with the eBay Partner Network for the site on which the item is listed.

To earn eBay affiliate commissions with your application, you must first be approved by the eBay Partner Network.

Note: eBay is no longer accepting applications.

Keep in mind that the use or distribution of an unapproved commission-generating application is a breach of the eBay Partner Network Agreement and may result in the termination of your affiliate account, as well as reversal of commissions.

Bot Blocking

If you make a PlaceOffer request and eBay returns a BotBlock container, your application must use the contents of the BotBlock container to verify that the application/user is not a bot. If you receive a botblock challenge in a PlaceOffer response, it looks similar to this:

<?xml version="1.0" encoding="utf-8" ?>
<eBay>
  <EBayTime>2007-06-02 20:03:49</EBayTime>
  <BotBlock>
    <BotBlockToken>FeIOAAAAAAA=</BotBlockToken>
    <BotBlockAudioUrl>Http://cgi.ebay.com/ws/eBayISAPI.dll?FetchAudioCaptcha&
      tokenString=FeIOAAAAAAA%3D&site_id=0&co_partnerId=0</BotBlockAudioUrl>
    <BotBlockURL>http://cgi.ebay.com/ws/eBayISAPI.dll?LoadBotImage&
      tokenString=FeIOAAAAAAA%3D</BotBlockURL>
  </BotBlock>
</eBay>

Capture the BotBlock container values (BotBlockUrl, BotBlockAudioUrl, and BotBlockToken) in the PlaceOffer response and input the respective value for BotBlockUrl or BotBlockAudioUrl in a new PlaceOffer call. Include a BotBlock container (with the user-input value and the token you captured from the BotBlockToken field). eBay then uses the values in your call to validate that the user is not a bot.

You can use GetChallengeToken to test your application's ability to show that PlaceOffer is not being called by a bot. Make a GetChallengeToken request and capture ChallengeToken, ImageChallengeURL, and AudioChallengeURL. The application/user must input the value for ImageChallengeURL or AudioChallengeURL. Your application must capture this value and, in a PlaceOffer call, include the appropriate values. The BotBlock container should contain the user-input value along with the value from ChallengeToken (from the GetChallengeToken response). eBay then uses your BotBlock container to validate that the user not a bot.

Testing PlaceOffer

You can test PlaceOffer in the Sandbox. Testing the call requires at least two test users: one to list the item as the seller and the other to make the offer as a buyer. However, to accommodate all listing type use cases, your test bed should use three or more test users (which allows for more than one buyer). The test user acting as the seller must have sufficient seller qualifications to list all auction types to be tested.

Test offers on all supported types of listings: a single-item fixed-price, and multi-item fixed-price. For multi-item fixed-price listings, make the offer for multiple items from the same listing (specified in the Offer.Quantity property).

Use GetSellerList, GetSellerEvents, and GetItem to view changes to listings after placing offers.

Test PlaceOffer under error conditions by deliberately specifying incorrect inputs. For example, specify an offer amount that is less than the current minimum bid amount.

Related Information

See:
    Best Offer
    API License Agreement
    eBay User Agreement
    PlaceOffer API License Agreement Addendum
    API Logo Usage Requirements
    Filing a Support Ticket
    eBay Partner Network

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"?>
<PlaceOfferRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Input Fields -->
  <AffiliateTrackingDetails> AffiliateTrackingDetailsType
    <AffiliateUserID> string </AffiliateUserID>
    <ApplicationDeviceType> ApplicationDeviceTypeCodeType </ApplicationDeviceType>
    <TrackingID> string </TrackingID>
    <TrackingPartnerCode> string </TrackingPartnerCode>
  </AffiliateTrackingDetails>
  <BlockOnWarning> boolean </BlockOnWarning>
  <ItemID> ItemIDType (string) </ItemID>
  <Offer> OfferType
    <Action> BidActionCodeType </Action>
    <BestOfferID> BestOfferIDType (string) </BestOfferID>
    <MaxBid> AmountType (double) </MaxBid>
    <Message> string </Message>
    <Quantity> int </Quantity>
    <UserConsent> boolean </UserConsent>
  </Offer>
  <VariationSpecifics> NameValueListArrayType
    <NameValueList> NameValueListType
      <Name> string </Name>
      <Value> string </Value>
      <!-- ... more Value values allowed here ... -->
    </NameValueList>
    <!-- ... more NameValueList nodes allowed here ... -->
  </VariationSpecifics>
  <!-- Standard Input Fields -->
  <BotBlock> BotBlockRequestType
    <BotBlockToken> string </BotBlockToken>
    <BotBlockUserInput> string </BotBlockUserInput>
  </BotBlock>
  <EndUserIP> string </EndUserIP>
  <ErrorLanguage> string </ErrorLanguage>
  <InvocationID> UUIDType (string) </InvocationID>
  <MessageID> string </MessageID>
  <Version> string </Version>
  <WarningLevel> WarningLevelCodeType </WarningLevel>
</PlaceOfferRequest>

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"?>
<PlaceOfferResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Output Fields -->
  <BestOffer> BestOfferType
    <BestOfferID> BestOfferIDType (string) </BestOfferID>
    <Status> BestOfferStatusCodeType </Status>
  </BestOffer>
  <OrderLineItemID> string </OrderLineItemID>
  <SellingStatus> SellingStatusType
    <ConvertedCurrentPrice currencyID="CurrencyCodeType"> AmountType (double) </ConvertedCurrentPrice>
    <CurrentPrice currencyID="CurrencyCodeType"> AmountType (double) </CurrentPrice>
    <HighBidder> UserType
      <UserID> UserIDType (string) </UserID>
    </HighBidder>
    <MinimumToBid currencyID="CurrencyCodeType"> AmountType (double) </MinimumToBid>
    <ReserveMet> boolean </ReserveMet>
    <SuggestedBidValues> SuggestedBidValueType
      <BidValue currencyID="CurrencyCodeType"> AmountType (double) </BidValue>
      <!-- ... more BidValue values allowed here ... -->
    </SuggestedBidValues>
  </SellingStatus>
  <TransactionID> string </TransactionID>
  <!-- Standard Output Fields -->
  <Ack> AckCodeType </Ack>
  <BotBlock> BotBlockResponseType
    <BotBlockAudioUrl> string </BotBlockAudioUrl>
    <BotBlockToken> string </BotBlockToken>
    <BotBlockUrl> string </BotBlockUrl>
  </BotBlock>
  <Build> string </Build>
  <CorrelationID> string </CorrelationID>
  <DuplicateInvocationDetails> DuplicateInvocationDetailsType
    <DuplicateInvocationID> UUIDType (string) </DuplicateInvocationID>
    <InvocationTrackingID> string </InvocationTrackingID>
    <Status> InvocationStatusType </Status>
  </DuplicateInvocationDetails>
  <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>
  <Message> string </Message>
  <Timestamp> dateTime </Timestamp>
  <Version> string </Version>
</PlaceOfferResponse>

Detail Controls

DetailLevel

This call does not support varying Detail Levels. You do not need to pass DetailLevel in the request.

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.

Available samples:

• Basic Call ↓ - Purchase a Chinese auction item with a Buy It Now option.
• Bids on a Chinese auction ↓ - Places a bid on a Chinese auction item.

Purchase a Chinese auction item with a Buy It Now option.

Description

A potential buyer (b********r) has found a Harry Potter book she wants to buy. The book is listed as a Chinese auction with a Buy It Now option, so she can purchase the book with an Offer.Action of Purchase. The potential buyer must know the Buy It Now price and item ID before calling PlaceOffer.

Important: There a many rules and guidelines for using PlaceOffer, see Policies and Guidelines.

Input

The required input for this sample includes the ItemID for the book, the Action with a value of Purchase, the MaxBid of 20.0 (the Buy It Now price of the book), in the currency of the listing site, and the Quantity value of 1 to purchase the single book.

XML format.

<?xml version="1.0" encoding="utf-8"?>
<PlaceOfferRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
  <eBayAuthToken>A*******3</eBayAuthToken>
  </RequesterCredentials>
  <EndUserIP>www.******.**.***</EndUserIP>
  <ItemID>1**********4</ItemID>
  <Offer>
    <Action>Purchase</Action>
    <Quantity>1</Quantity>
    <MaxBid currencyID="USD">20.0</MaxBid>
  </Offer>
</PlaceOfferRequest>

Output

The important information in the response is in SellingStatus. The SellingStatus.HighBidder.UserID indicates that Bountiful Buyer was successful in her purchase at the CurrentPrice of $20 US dollars.

XML format.
<PlaceOfferResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2019-11-06T17:35:23.110Z</Timestamp>
  <Ack>Success</Ack>
  <Version>1125</Version>
  <Build>E1125_CORE_API_19070409_R1</Build>
  <SellingStatus>
    <ConvertedCurrentPrice currencyID="USD">20.0</ConvertedCurrentPrice>
    <CurrentPrice currencyID="USD">20.0</CurrentPrice>
    <HighBidder>
      <UserID>b********r</UserID>
    </HighBidder>
  </SellingStatus>
  <TransactionID>0</TransactionID>
</PlaceOfferResponse>

Back to list of samples

Places a bid on a Chinese auction item.

Description

A potential buyer is very excited about the rare Harry Potter that she has found on eBay and wants to place a bid on the auction with the goal of purchasing the item.

Input

While the starting bid for the item is $1.00 US dollars, the potential buyer has a feeling the volume is worth more than that. She places the first bid on the item, submitting the bid for $5.00 US dollars.

XML format.

<?xml version="1.0" encoding="utf-8"?>
<PlaceOfferRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
    <eBayAuthToken>A*******3</eBayAuthToken>
  </RequesterCredentials>
  <EndUserIP>www.******.**.***</EndUserIP>
  <ItemID>1**********2</ItemID>
  <Offer>
    <Action>Bid</Action>
    <Quantity>1</Quantity>
    <MaxBid currencyID="USD">5.00</MaxBid>
  </Offer>
</PlaceOfferRequest>

Output

The bid is successful, which can be gained from the fact that the CurrentPrice returns with a value of 1.0 (the currencyID is set to USD, indicating the price is in US dollars). The potential buyer b********r now has the leading bid for the item.

XML format.
<PlaceOfferResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2019-11-06T17:35:23.110Z</Timestamp>
  <Ack>Success</Ack>
  <Version>1125</Version>
  <Build>E1125_CORE_API_19070409_R1</Build>
  <UsageData>MTMyOTUyMTQ2LzE0NjU3Ow**</UsageData>
  <SellingStatus>
    <ConvertedCurrentPrice currencyID="USD">1.0</ConvertedCurrentPrice>
    <CurrentPrice currencyID="USD">1.0</CurrentPrice>
    <HighBidder>
      <UserID>b********r</UserID>
    </HighBidder>
    <MinimumToBid currencyID="USD">1.25</MinimumToBid>
  </SellingStatus>
</PlaceOfferResponse>

Back to list of samples

Change History