eBay Trading API Call Reference Version 643 Support     Knowledge Base     Forums     All Tutorials     All Code Samples Trading API Guide Call Reference Making an API Call Tutorials Release Notes

List of All Calls Field Index Enumeration Index Type Index Deprecated Objects Errors by Number Input Output Detail Controls Samples Change History Top Errors for PlaceOffer

Enables a user to bid (make an offer) on an item or make a best offer. For competitive-bid auction listings (such as a Chinese auction), a user can make a bid. For fixed-price listings (Basic Fixed-Price and eBay Stores Inventory listings), a user can purchase an item. A user can make a best offer on an item for which Best Offer is enabled. For information about the Best Offer feature (including rules for counteroffers), see Enabling Best Offer.

For more information about each use of PlaceOffer (including information about making a best offer or counteroffer, and information about accepting or declining a counteroffer), please see PlaceOffer Input.

Important note: Before using this call, please carefully review the PlaceOffer Policies and Guidelines. The PlaceOffer Policies are required for use of PlaceOffer in the production environment. Please carefully write your application to follow all the PlaceOffer Policies.

Note: PlaceOffer is available for evaluation by all in the Sandbox (test) environment.

For information about becoming authorized to use PlaceOffer in the Production environment, please contact Developer Relations, developer-relations@ebay.com.

Important notes: When you use PlaceOffer to make a best offer, no affiliate-related commissions are paid. 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.

If you make a PlaceOffer request and eBay returns a BotBlock container, your application must use the contents of the BotBlock container to show that the application-user is a human and not a bot.

Capture the contents of the BotBlock container (BotBlockUrl, BotBlockAudioUrl, and BotBlockToken) returned by PlaceOffer. The application-user must input the value for BotBlockUrl or BotBlockAudioUrl. Your application must capture this value and, in the next PlaceOffer call, include a BotBlock container (containing the user-input value and the token you captured from the BotBlockToken field). eBay then uses your BotBlock container (in your second PlaceOffer call) to validate that the user is a human and not a bot.

You can use GetChallengeToken to test your application's ability to show that a PlaceOffer user is a human and not 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 a BotBlock container. The BotBlock container will 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 is a human and not a bot.

If PayPal is the required payment method, then the user making a bid or purchase must have a PayPal account.

If a user has placed a bid on an item with Bid Assistant (available on the eBay site), then a subsequent PlaceOffer call on behalf of that user, on that item, will not succeed.

See PlaceOffer.

See also the reference documentation for these calls:

• GetChallengeToken - Retrieves a botblock token and URLs for an image or audio clip that the user is to match.
• GetBestOffers - Retrieves the best offers associated with an ItemID according to the BestOfferStatus filter, where Active is the default value. Specify a best offer ID to retrieve the details for a specific best offer.

Back to top

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

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">
  <!-- 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>
  <!-- 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 nodes here ... -->
    </NameValueList>
    <!-- ... more NameValueList nodes here ... -->
  </VariationSpecifics>
</PlaceOfferRequest>

Back to top

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

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

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"?>
<PlaceOfferResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- 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 here ... -->
    <LongMessage> string </LongMessage>
    <SeverityCode> SeverityCodeType </SeverityCode>
    <ShortMessage> string </ShortMessage>
  </Errors>
  <!-- ... more Errors nodes here ... -->
  <HardExpirationWarning> string </HardExpirationWarning>
  <Message> string </Message>
  <Timestamp> dateTime </Timestamp>
  <Version> string </Version>
  <!-- Call-specific Output Fields -->
  <BestOffer> BestOfferType 
    <BestOfferID> BestOfferIDType (string) </BestOfferID>
    <Status> BestOfferStatusCodeType </Status>
  </BestOffer>
  <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>
  </SellingStatus>
  <TransactionID> string </TransactionID>
</PlaceOfferResponse>

Back to top

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

Back to top

New to making API calls? Please see Routing the Request.

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 fixed price or BuyItNow item.
• Purchases an Item Variation ↓ - Purchases one item from a listing with Item Variations.

Purchase a fixed price or BuyItNow item.

Description

braggybuyer has found a Harry Potter book he wants to buy. The book is a fixed-priced listing, so he can purchase the book with PlaceOffer. braggy buyer must know the current price and listing type before using PlaceOffer.

Important: There a many rules and guidelines for using PlaceOffer, see PlaceOffer Best Practices in the Web Services Guide.

Input

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

XML format (HTTP POST). Also available is the .txt version of this XML.

<?xml version="1.0" encoding="utf-8"?>
<PlaceOfferRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
    <eBayAuthToken>ABC...123</eBayAuthToken>
  </RequesterCredentials>
  <ItemID>110025737350</ItemID>
  <EndUserIP>ww.xxx.yy.zzz</EndUserIP>
  <Offer>
    <Action>Purchase</Action>
    <MaxBid currencyID="USD">10</MaxBid>
    <Quantity>1</Quantity>
  </Offer>
</PlaceOfferRequest>

Output

The important information in the response is in SellingStatus. The SellingStatus.HighBidder.UserID indicates braggybuyer was successful in his purchase at the CurrentPrice of 10 US dollars.

XML format. Also available is the .txt version of this XML.

<?xml version="1.0" encoding="utf-8"?>
<PlaceOfferResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2007-12-04T22:18:38.579Z</Timestamp>
  <Ack>Success</Ack>
  <Version>539</Version>
  <Build>e539_core_Bundled_5642307_R1</Build>
  <SellingStatus>
    <ConvertedCurrentPrice currencyID="USD">10.0</ConvertedCurrentPrice>
    <CurrentPrice currencyID="USD">10.0</CurrentPrice>
    <HighBidder>
      <UserID>braggybuyer</UserID>
    </HighBidder>
  </SellingStatus>
  <TransactionID>0</TransactionID>
</PlaceOfferResponse>

Back to list of samples

Purchases one item from a listing with Item Variations.

Description

User bountifulbuyer has searched for and found a listing with women's Polo tops in several colors. The listing organized the tops by using Item Variations.

She wants to buy two medium pink tops for $17.99 each and a medium black top for $20.00. As pink and black are different variations, she can't buy them at the same time. (She needs to use separate PlaceOffer requests.) In the sample below, she is purchasing the two pink tops only.

Input

The key inputs in this scenario are the ItemID and VariationSpecifics, which uniquely identify the variation she wants to purchase, along with the Quantity. (These details were determined based on a GetItem response.)

The application needs to completely specify all the variation's VariationSpecifics in order to uniquely identify that variation within the specified listing.

XML format (HTTP POST). Also available is the .txt version of this XML.

<?xml version="1.0" encoding="utf-8"?>
<PlaceOfferRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <ErrorLanguage>en_US</ErrorLanguage>
  <ItemID>110039490209</ItemID>  
  <VariationSpecifics>
    <NameValueList>
      <Name>Color</Name>
      <Value>Pink</Value>
    </NameValueList>
    <NameValueList>
      <Name>Size</Name>
      <Value>M</Value>
    </NameValueList>
  </VariationSpecifics>
  <Offer>
    <Action>Purchase</Action>
    <MaxBid currencyID="USD">17.99</MaxBid>
    <Quantity>2</Quantity>
  </Offer>
  <RequesterCredentials>
    <eBayAuthToken>ABC...123</eBayAuthToken>
  </RequesterCredentials>
</PlaceOfferRequest>

Output

The important information in the response is TransactionID, which indicates that the purchase was recorded by eBay. She can use the value as input to GetItemTransactions to verify the amount paid (before shipping), the quantity purchased, and which variation she purchased.

XML format. Also available is the .txt version of this XML.

<?xml version="1.0" encoding="utf-8"?>
<PlaceOfferResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2009-06-12T14:26:17.590Z</Timestamp>
  <Ack>Success</Ack>
  <Version>619</Version>
  <Build>e619__Bundled_9183565_R1</Build>
  <SellingStatus>
    <ConvertedCurrentPrice currencyID="USD">17.99</ConvertedCurrentPrice>
    <CurrentPrice currencyID="USD">17.99</CurrentPrice>
    <HighBidder>
      <UserID>testuser_bountifulbuyer</UserID>
    </HighBidder>
  </SellingStatus>
  <TransactionID>24005469001</TransactionID>
</PlaceOfferResponse>

Back to list of samples

Back to top

This document was generated with a customized version of the apireferencedocs tool.

© 2005–2009 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.