GetSingleItem - Call Reference - eBay Shopping Web Services

GetSingleItem

GetSingleItem gets publicly visible details about one listing on eBay. This gives you most of the data that eBay shows to the general public on the View Item page (title, description, basic price information, and other details).

See the Input and Output sections below for a complete list of fields in this call.

You just need to know the eBay item ID (a value like 123456789012) in order to retrieve the listing. Typically, you use FindItems to find listings by keyword or by seller, then use the ItemID value from one of those items as input to GetSingleItem. If a listing ended more than 90 days ago, its title, price, and other item information are not returned.

Note: What if you need to see item data that is normally only visible to the seller (where eBay would require them to login)? For this, you would need to use the authenticated version of this call (GetItem) in eBay Trading Web Services instead.

Best Practices

GetSingleItem has been optimized for response size, speed and usability. So, it returns the most commonly used fields by default. Use the IncludeSelector field to get more data—but please note that getting more data can result in longer response times.

See Sample: Basic Call for a sample that returns the default fields. See Sample: Getting the Full Description and Item Specifics for a sample that returns more data.

Refreshing Item Data

If you're monitoring the same item over time, most of the data (such as the seller and the full text of the description) doesn't change at all, or changes rarely. A few pieces of information (like the bid count) change more often.

So, after you initially retrieve an item's details, cache the item data locally, and then use GetItemStatus from then on to more quickly update the details that tend to change. Depending on your use case, you can call GetSingleItem again occasionally to see if the seller has revised any other data in the listing.

Getting Shipping Details

If you want to see an item's shipping cost summary, specify ShippingCosts in IncludeSelector.

See Sample: Including a Shipping Cost Summary for a sample that shows how to add a listing's shipping cost summary to the default results.

Once you know the item has shipping costs, you can call GetShippingCosts with the same item ID if you need more shipping details.

If you're showing an item to a potential buyer and you know where that buyer is located, it may be helpful to check where the seller is willing to ship the item (ShipToLocations). Some sellers will ship worldwide, and others prefer to ship to certain countries or regions only.

Getting an Item from a Different eBay Site

Item IDs are unique across all eBay sites, so you normally don't need to specify a different site ID with your GetSingleItem request to get an item that was listed on another eBay site. (This is a little different from the way FindItems works.)

In fact, if you send your request to the US site and the item was listed on the eBay UK site, we'll give you the original price in Pounds (GBP), and we'll calculate the converted price in US dollars (USD) for you (based on the current exchange rate).

See Sample: Getting a Foreign Listing with Converted Prices for a sample that shows how this works.

By the way, we always return converted prices, even when no conversion takes place. So, if you're comparing the current price of different items and you don't care which site they're listed on, it is simplest to compare the ConvertedCurrentPrice values of each item.

More Tips

If you discover other useful practices, feel free to add them in the User-Contributed Notes at the bottom of this page.

If you're looking for more tips, try searching the Knowledge Base and Developer Forums.

For information about specifying affiliate parameters, see Affiliate URL Parameters and HTTP Header Values.

Related calls:

FindItems - Searches for items based on a query or a seller ID. If you use keywords, this call returns items that contain the keywords in the title. A maximum of 50 items is returned.
GetItemStatus - Allows you to get the status for a group of items. Returns status information such as ListingStatus and End Time for all items that are listed in the request. Duplicated items are returned as a single item.
GetShippingCosts - Gets shipping costs for an item.
GetSingleItem - Gets publicly visible details about one listing. This gives you most of the data that eBay shows on the View Item page (title, description, price, and other details).

GetSingleItem Input

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

Argument	Type	Reqd?	Meaning
Standard Input Fields [Jump to call-specific fields]
MessageID	string	Optional	If you pass a value in MessageID in a request, we'll return the same value in CorrelationID in the response. If you're making a lot of calls, you can use this for tracking that a response is returned for every request and to match particular responses to particular requests. (In this case, specify a different value for each request.) You can specify any value that is useful to you.
Call-specific Input Fields
IncludeSelector	string	Optional	Defines standard subsets of fields to return within the response. If you don't specify this field, the call returns a default set of fields (see the "Detail Controls" link below). If you specify this field, the additional fields you retrieve can affect the call's response time (performance). Applicable values: • Details Include most available fields in the response (except fields that significantly affect the call's performance). • Description Include the Description field in the response. (This can affect the call's performance.) • TextDescription Include the text Description(no html tag) field in the response. (This can affect the call's performance.) • ShippingCosts Include basic shipping costs in the response. (Use GetShippingCosts to retrieve more details.) • ItemSpecifics Include ItemSpecifics in the response. Use a comma to specify multiple values. (In this case, the results are cumulative.) See "GetSingleItem Samples" for an example of how to use this field. See "Detail Controls" for a complete list of fields that can be returned for each selector. See: Detail Controls GetSingleItem Samples
ItemID	string	Required	The item ID that uniquely identifies the item listing for which to retrieve the data. You can determine an item's ID by calling FindItems or from the eBay Web site. Max length: 19 (Note: The eBay database specifies 38. Currently, Item IDs are usually 9 to 12 digits). See (FindItems) Item.ItemID.

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

<?xml version="1.0" encoding="utf-8"?>
<GetSingleItemResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- 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 here ... -->
    <LongMessage> string </LongMessage>
    <SeverityCode> SeverityCodeType </SeverityCode>
    <ShortMessage> string </ShortMessage>
  </Errors>
  <!-- ... more Errors nodes here ... -->
  <Timestamp> dateTime </Timestamp>
  <Version> string </Version>
  <!-- Call-specific Output Fields -->
  <Item> SimpleItemType 
    <AutoPay> boolean </AutoPay>
    <BestOfferEnabled> boolean </BestOfferEnabled>
    <BidCount> int </BidCount>
    <BusinessSellerDetails> BusinessSellerDetailsType 
      <AdditionalContactInformation> string </AdditionalContactInformation>
      <Address> AddressType 
        <FirstName> string </FirstName>
        <LastName> string </LastName>
      </Address>
      <Email> string </Email>
      <Fax> string </Fax>
      <LegalInvoice> boolean </LegalInvoice>
      <TermsAndConditions> string </TermsAndConditions>
      <TradeRegistrationNumber> string </TradeRegistrationNumber>
      <VATDetails> VATDetailsType 
        <VATID> string </VATID>
        <VATSite> string </VATSite>
      </VATDetails>
    </BusinessSellerDetails>
    <BuyItNowAvailable> boolean </BuyItNowAvailable>
    <BuyItNowPrice currencyID="CurrencyCodeType"> AmountType (double) </BuyItNowPrice>
    <Charity> CharityType 
      <CharityID> string </CharityID>
      <CharityName> string </CharityName>
      <CharityNumber> int </CharityNumber>
      <DonationPercent> float </DonationPercent>
      <LogoURL> string </LogoURL>
      <Mission> string </Mission>
      <Status> CharityStatusCodeType </Status>
    </Charity>
    <ConvertedBuyItNowPrice currencyID="CurrencyCodeType"> AmountType (double) </ConvertedBuyItNowPrice>
    <ConvertedCurrentPrice currencyID="CurrencyCodeType"> AmountType (double) </ConvertedCurrentPrice>
    <Country> CountryCodeType </Country>
    <CurrentPrice currencyID="CurrencyCodeType"> AmountType (double) </CurrentPrice>
    <Description> string </Description>
    <EndTime> dateTime </EndTime>
    <GalleryURL> anyURI </GalleryURL>
    <HighBidder> SimpleUserType 
      <FeedbackPrivate> boolean </FeedbackPrivate>
      <FeedbackRatingStar> FeedbackRatingStarCodeType </FeedbackRatingStar>
      <FeedbackScore> int </FeedbackScore>
      <UserAnonymized> boolean </UserAnonymized>
      <UserID> string </UserID>
    </HighBidder>
    <HitCount> long </HitCount>
    <ItemID> string </ItemID>
    <ItemSpecifics> NameValueListArrayType 
      <NameValueList> NameValueListType 
        <Name> string </Name>
        <Value> string </Value>
        <!-- ... more Value nodes here ... -->
      </NameValueList>
      <!-- ... more NameValueList nodes here ... -->
    </ItemSpecifics>
    <ListingStatus> ListingStatusCodeType </ListingStatus>
    <ListingType> ListingTypeCodeType </ListingType>
    <Location> string </Location>
    <MinimumToBid currencyID="CurrencyCodeType"> AmountType (double) </MinimumToBid>
    <PaymentAllowedSite> SiteCodeType </PaymentAllowedSite>
    <!-- ... more PaymentAllowedSite nodes here ... -->
    <PaymentMethods> BuyerPaymentMethodCodeType </PaymentMethods>
    <!-- ... more PaymentMethods nodes here ... -->
    <PictureURL> anyURI </PictureURL>
    <!-- ... more PictureURL nodes here ... -->
    <PostalCode> string </PostalCode>
    <PrimaryCategoryID> string </PrimaryCategoryID>
    <PrimaryCategoryIDPath> string </PrimaryCategoryIDPath>
    <PrimaryCategoryName> string </PrimaryCategoryName>
    <ProductID> ProductIDType (string) </ProductID>
    <Quantity> int </Quantity>
    <QuantitySold> int </QuantitySold>
    <ReserveMet> boolean </ReserveMet>
    <ReturnPolicy> ReturnPolicyType 
      <Description> string </Description>
      <EAN> string </EAN>
      <Refund> string </Refund>
      <ReturnsAccepted> string </ReturnsAccepted>
      <ReturnsWithin> string </ReturnsWithin>
      <ShippingCostPaidBy> string </ShippingCostPaidBy>
      <WarrantyDuration> string </WarrantyDuration>
      <WarrantyOffered> string </WarrantyOffered>
      <WarrantyType> string </WarrantyType>
    </ReturnPolicy>
    <SecondaryCategoryID> string </SecondaryCategoryID>
    <SecondaryCategoryIDPath> string </SecondaryCategoryIDPath>
    <SecondaryCategoryName> string </SecondaryCategoryName>
    <Seller> SimpleUserType 
      <FeedbackPrivate> boolean </FeedbackPrivate>
      <FeedbackRatingStar> FeedbackRatingStarCodeType </FeedbackRatingStar>
      <FeedbackScore> int </FeedbackScore>
      <PositiveFeedbackPercent> float </PositiveFeedbackPercent>
      <UserID> string </UserID>
    </Seller>
    <ShippingCostSummary> ShippingCostSummaryType 
      <InsuranceCost currencyID="CurrencyCodeType"> AmountType (double) </InsuranceCost>
      <ShippingServiceCost currencyID="CurrencyCodeType"> AmountType (double) </ShippingServiceCost>
      <ShippingType> ShippingTypeCodeType </ShippingType>
    </ShippingCostSummary>
    <ShipToLocations> string </ShipToLocations>
    <!-- ... more ShipToLocations nodes here ... -->
    <Site> SiteCodeType </Site>
    <StartTime> dateTime </StartTime>
    <Subtitle> string </Subtitle>
    <TimeLeft> duration </TimeLeft>
    <Title> string </Title>
    <ViewItemURLForNaturalSearch> anyURI </ViewItemURLForNaturalSearch>
  </Item>
</GetSingleItemResponse>

Return Value	Type	Returned?	Meaning
Standard Output Fields [Jump to call-specific fields]
Ack	AckCodeType	Always	Indicates whether the call was successfully processed by eBay. Applicable values: • CustomCode (out) Reserved for internal or future use. • Failure (out) Request processing failed • Success (out) Request processing succeeded • Warning (out) Request processing completed with warning information being included in the response message (Not all values in AckCodeType apply to this field.)
Build	string	Always	This refers to the particular software build that eBay used when processing the request and generating the response. This includes the version number plus additional information. eBay Developer Support may request the build information when helping you resolve technical issues.
CorrelationID	string	Conditionally	If you pass a value in MessageID in a request, we will return the same value in CorrelationID in the response. You can use this for tracking that a response is returned for every request and to match particular responses to particular requests. Only returned if MessageID was used.
Errors	ErrorType (repeatable)	Conditionally	A list of application-level errors or warnings (if any) that were raised when eBay processed the request. Application-level errors occur due to problems with business-level data on the client side or on the eBay server side. For example, an error would occur if the request contains an invalid combination of fields, or it is missing a required field, or the value of the field is not recognized. An error could also occur if eBay encountered a problem in our internal business logic while processing the request. Only returned if there were warnings or errors.
Errors.ErrorClassification	ErrorClassificationCodeType	Conditionally	API errors are divided between two classes: system errors and request errors. Applicable values: • CustomCode (out) Reserved for internal or future use. • RequestError (out) An error has occurred either as a result of a problem in the sending application or because the application's end-user has attempted to submit invalid data (or missing data). In these cases, do not retry the request. The problem must be corrected before the request can be made again. If the problem is due to something in the application (such as a missing required field), the application must be changed. If the problem is a result of end-user data, the application must alert the end-user to the problem and provide the means for the end-user to correct the data. Once the problem in the application or data is resolved, resend the request to eBay with the corrected data. • SystemError (out) Indicates that an error has occurred on the eBay system side, such as a database or server down. An application can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form. See Errors by Number.
Errors.ErrorCode	token	Conditionally	A unique code that identifies the particular error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. See Errors by Number.
Errors.ErrorParameters	ErrorParameterType (repeatable)	Conditionally	Some warning and error messages return one or more variables that contain contextual information about the error. This is often the field or value that triggered the error. You can usually predict where these will occur by looking at the "replaceable_value" indicators in our Errors by Number page. See Errors by Number.
Errors.ErrorParameters [ attribute ParamID ]	string	Conditionally	The index of the parameter in the error.
Errors.ErrorParameters.Value	string	Conditionally	The value of the variable.
Errors.LongMessage	string	Conditionally	A more detailed description of the condition that raised the error. See Errors by Number.
Errors.SeverityCode	SeverityCodeType	Conditionally	Indicates whether the error caused the request to fail. If the request fails and the source of the problem is within the application (such as a missing required element), please change the application before you retry the request. If the problem is due to end-user input data, please alert the end-user to the problem and provide the means for them to correct the data. Once the problem in the application or data is resolved, you can attempt to re-send the request to eBay. If the source of the problem is on eBay's side, you can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form. When a warning occurs, the error is returned in addition to the business data. In this case, you do not need to retry the request (as the original request was successful). However, depending on the cause or nature of the warning, you might need to contact either the end user or eBay to effect a long term solution to the problem to prevent it from reoccurring in the future. Applicable values: • CustomCode (out) Reserved for internal or future use • Error (out) The request that triggered the error was not processed successfully. When a serious application-level error occurs, the error is returned instead of the business data. • Warning (out) The request was processed successfully, but something occurred that may affect your application or the user. For example, eBay may have changed a value the user sent in. In this case, eBay returns a normal, successful response and also returns the warning. See: Errors by Number Requirements for Error Handling for more information (in the eBay Trading Web Services guide)
Errors.ShortMessage	string	Conditionally	A brief description of the condition that raised the error. See Errors by Number.
Timestamp	dateTime	Always	This value represents the date and time when eBay processed the request. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about this time format and converting to and from the GMT time zone.
Version	string	Always	The release version that eBay used to process the request. Note: This is usually the latest release version, as specified in the release notes. (eBay releases the API to international sites about a week after we release it to the US site.) If a field in the response returns the token "CustomCode", it usually means that the field is a code type (a token or enumeration), and that in your request URL (or HTTP header) you specified a version that is older than the version in which the token was added to the call. See eBay Versioning Strategy.
Call-specific Output Fields
Item	SimpleItemType	Always	Contains details about the listing whose ID was specified in the request. IncludeSelector: Description, Details, ItemSpecifics, ShippingCosts. Also returned if IncludeSelector is not provided on input.
Item.AutoPay	boolean	Always	If true, the seller requests immediate payment for the item. If false or not specified, immediate payment is not requested. (In responses, does not indicate whether the item is actually still a candidate for purchase via immediate payment.) Only applicable to items listed on PayPal-enabled sites in categories that support immediate payment (see AutoPayEnabled in GetCategories), when seller has a Premier or Business PayPal account (see PayPalAccountType in Getuser). If true, the seller must also accept PayPal as a payment method for the item (see Item.PaymentMethods). Required for digitally delivered goods (see Item.DigitalDeliveryDetails). Not supported if ThirdPartyCheckout is true. See the eBay Web Services guide section on Immediate Payment for additional requirements and dependencies. Also see the section on working with the eBay Motors site for additional rules. Not applicable to Half.com. IncludeSelector: Details. Also returned if IncludeSelector is not provided on input.
Item.BestOfferEnabled	boolean	Always	Whether the seller will accept a best offer for this item. This feature enables a buyer to make a lower-priced binding offer on a fixed price item. Buyers can't see how many offers have been made (only the seller can see this information). To make a best offer on a listing, use the eBay Web site. IncludeSelector: Details. See: (eBay Help) Making a Best Offer (for Buyers) (eBay DE Hilfe) Preis vorschlagen
Item.BidCount	int	Conditionally	The number of bids that have been placed on the item. On most sites, once a Chinese auction has bids, the listing is no longer eligible for Buy It Now. (This is not necessarily true for Dutch auctions. See Item.BuyItNowAvailable for Dutch auctions.) IncludeSelector: Description, Details, ItemSpecifics, ShippingCosts. Also returned if IncludeSelector is not provided on input.
Item.BusinessSellerDetails	BusinessSellerDetailsType	Conditionally	Returns the seller's information (in a business card format) for the GetSingleItem call, if the seller's SellerBusinessCodeType is set to 'Commercial'. This is only applicable for sites where Business Seller options are supported. IncludeSelector: Details.
Item.BusinessSellerDetails .AdditionalContactInformation	string	Conditionally	Displays the AdditionalContactInformation of the seller (in a business card format) as part of the data returned in the GetSingleItem call if the seller's SellerBusinessCodeType is set to 'Commercial'. IncludeSelector: Details.
Item.BusinessSellerDetails .Address	AddressType	Conditionally	Displays the Address of the seller (in a business card format) as part of the data returned in the GetSingleItem call if the seller's SellerBusinessCodeType is set to 'Commercial'. IncludeSelector: Details.
Item.BusinessSellerDetails .Address.FirstName	string	Conditionally	Displays the first name of the seller (in a business card format) if the seller's SellerBusinessCodeType is set to 'Commercial'. IncludeSelector: Details.
Item.BusinessSellerDetails .Address.LastName	string	Conditionally	Displays the last name of the seller (in a business card format) if the seller's SellerBusinessCodeType is set to 'Commercial'. IncludeSelector: Details.
Item.BusinessSellerDetails .Email	string	Conditionally	Displays the email address of the seller (in a business card format) as part of the data returned in the GetSingleItem call if the seller's SellerBusinessCodeType is set to 'Commercial'. IncludeSelector: Details.
Item.BusinessSellerDetails.Fax	string	Conditionally	Displays the fax number of the seller (in a business card format) as part of the data returned in the GetSingleItem call if the seller's SellerBusinessCodeType is set to 'Commercial'. IncludeSelector: Details.
Item.BusinessSellerDetails .LegalInvoice	boolean	Conditionally	Displays the LegalInvoice of the seller (in a business card format) as part of the data returned in the GetSingleItem call if the seller's SellerBusinessCodeType is set to 'Commercial'. IncludeSelector: Details.
Item.BusinessSellerDetails .TermsAndConditions	string	Conditionally	Displays the TermsAndConditions of the seller (in a business card format) as part of the data returned in the GetSingleItem call if the seller's SellerBusinessCodeType is set to 'Commercial'. IncludeSelector: Details.
Item.BusinessSellerDetails .TradeRegistrationNumber	string	Conditionally	Displays the TradeRegistrationNumber of the seller (in a business card format) as part of the data returned in the GetSingleItem call if the seller's SellerBusinessCodeType is set to 'Commercial'. IncludeSelector: Details.
Item.BusinessSellerDetails .VATDetails	VATDetailsType	Conditionally	Displays the VATDetails of the seller (in a business card format) as part of the data returned in the GetSingleItem call if the seller's SellerBusinessCodeType is set to 'Commercial'. IncludeSelector: Details.
Item.BusinessSellerDetails .VATDetails.VATID	string	Conditionally	Displays the VatSite Id of the seller (in a business card format) as part of the data returned in the GetSingleItem call if the seller's SellerBusinessCodeType is set to 'Commercial'. IncludeSelector: Details.
Item.BusinessSellerDetails .VATDetails.VATSite	string	Conditionally	Displays the VatSite Id of the seller (in a business card format) as part of the data returned in GetSingleItem call if the seller's SellerBusinessCodeType is set to 'Commercial'. IncludeSelector: Details.
Item.BuyItNowAvailable	boolean	Conditionally	For Dutch auctions (not Chinese auctions) this indicates whether there is a Buy It Now option. (On some sites, the Buy It Now option remains available for Dutch auctions even after there are bids.) Applicable to the Germany site (site ID 77) only. This field is returned only if the value is true. IncludeSelector: Description, Details, ItemSpecifics, ShippingCosts. Also returned if IncludeSelector is not provided on input.
Item.BuyItNowPrice	AmountType (double)	Conditionally	The Buy It Now Price of the item (if any), in the currency of the site on which the item was listed. For Chinese auctions (Quantity=1, competitive bidding online auctions), Buy It Now lets a user purchase the item at a fixed price and end the auction immediately. On most sites, after a Chinese auction has bids, the listing is no longer eligible for Buy It Now. However, calls can still return the Buy It Now Price that the seller set for the listing. Use the Item.BidCount field to determine whether an auction with Buy It Now has bids or not. Some eBay sites also support Buy It Now for Dutch auctions (multi-quantity, competitive bidding), where you can buy multiple items from the same listing at a fixed price, instead of bidding. On some sites, the Buy It Now option remains available for Dutch auctions even after there are bids. See Item.BuyItNowAvailable. For fixed-price (FixedPriceItem) and Store Inventory listings (StoresFixedPrice), see CurrentPrice or ConvertedCurrentPrice instead. Only returned if an item was listed with Buy It Now. IncludeSelector: Details. See: (GetSingleItem) Item.ListingType Item.BuyItNowAvailable Item.ConvertedBuyItNowPrice Item.ConvertedCurrentPrice (eBay Help) Buying with Buy It Now (eBay DE Hilfe) Kaufen mit Sofort-Kaufen
Item.BuyItNowPrice [ attribute currencyID ]	CurrencyCodeType	Conditionally	Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType.
Item.Charity	CharityType	Conditionally	Identifier for a Giving Works listing and the benefiting nonprofit charity organization. IncludeSelector: Details.
Item.Charity.CharityID	string	Conditionally	A unique identification number assigned by eBay to registered nonprofit charity organizations. IncludeSelector: Details.
Item.Charity.CharityName	string	Conditionally	The name of the benefiting nonprofit charity organization selected by the charity seller. IncludeSelector: Details.
Item.Charity.CharityNumber	int	Conditionally	A unique identification number assigned to a nonprofit charity organization by the dedicated provider of eBay Giving Works. Being superseded by CharityID. Max 10 digits. IncludeSelector: Details.
Item.Charity.DonationPercent	float	Conditionally	The percentage of the purchase price that the seller chooses to donate to the selected nonprofit organization. This percentage is displayed in the Giving Works item listing. Possible values: 10.0 to 100.0. Percentages must increment by 5.0. Minimum donation percentages may be required for Giving Works listings, see http://pages.ebay.com/help/sell/selling-nonprofit.html for details. DonationPercent is required input when listing Giving Works items. IncludeSelector: Details.
Item.Charity.LogoURL	string	Conditionally	The URL of the nonprofit charity organization. This URL is displayed in the Giving Works item listing. IncludeSelector: Details.
Item.Charity.Mission	string	Conditionally	The stated mission of the nonprofit charity organization. This mission is displayed in the Giving Works item listing. IncludeSelector: Details.
Item.Charity.Status	CharityStatusCodeType	Conditionally	The status of the nonprofit charity organization. Applicable values: • CustomCode (out) Reserved for internal or future use. • NoLongerValid (out) The specified nonprofit charity organization is no longer a valid nonprofit charity organization according to the requirements of the dedicated eBay Giving Works provider. • Valid (out) The specified nonprofit charity organization is a valid nonprofit charity organization according to the requirements of the dedicated eBay Giving Works provider. IncludeSelector: Details.
Item.ConvertedBuyItNowPrice	AmountType (double)	Conditionally	The listing's Buy It Now Price (if any), converted into the currency of the site to which you sent this request. Price fields are returned as doubles, not necessarily in the traditional monetary format of the site's country. For example, a US Dollar value might be returned as 3.880001 instead of 3.88. For Chinese auctions (Quantity=1, competitive bidding online auctions), Buy It Now lets a user purchase the item at a fixed price and end the auction immediately. On most sites, after a Chinese auction has bids, the listing is no longer eligible for Buy It Now. However, calls like FindItems still return the Buy It Now Price that the seller set for the listing. Use the Item.BidCount field to determine whether an auction with Buy It Now has bids or not (and therefore whether it is still eligible to be purchased with Buy It Now). Some eBay sites also support Buy It Now for Dutch auctions (multi-quantity, competitive bidding), where you can buy multiple items from the same listing at a fixed price, instead of bidding. On some sites, the Buy It Now option remains available for Dutch auctions even after there are bids. See Item.BuyItNowAvailable. For fixed-price (FixedPriceItem) and Store Inventory listings (StoresFixedPrice), see CurrentPrice or ConvertedCurrentPrice instead. Only returned if an item was listed with Buy It Now. For active items, refresh this value every 24 hours to pick up the current conversion rates (if this value has been converted). IncludeSelector: Description, Details, ItemSpecifics, ShippingCosts. Also returned if IncludeSelector is not provided on input. See: (GetSingleItem) Item.ListingType Item.BuyItNowAvailable Item.BuyItNowPrice Item.ConvertedCurrentPrice (eBay Help) Buying with Buy It Now (eBay DE Hilfe) Kaufen mit Sofort-Kaufen
Item.ConvertedBuyItNowPrice [ attribute currencyID ]	CurrencyCodeType	Conditionally	Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType.
Item.ConvertedCurrentPrice	AmountType (double)	Conditionally	The listing's current price, converted to the currency of the site specified in the request. If the item is a multi-quantity listing, this is the price of one item. Price fields are returned as doubles, not necessarily in the usual monetary amount format of the site. For example, a US Dollar value might be returned as 3.879938 instead of 3.88. For competitive-bidding listings (Chinese and Dutch auctions), this is the current minimum bid price (if the listing has no bids) or the current high bid (if the listing has bids). (Compare to BuyItNowPrice). For Basic Fixed-Price (FixedPriceItem), Store Inventory (StoresFixedPrice), and Ad format (AdType) listings, this is the current fixed price. For active items, refresh this value every 24 hours to pick up the current conversion rates (if this value has been converted). IncludeSelector: Description, Details, ItemSpecifics, ShippingCosts. Also returned if IncludeSelector is not provided on input. See (GetSingleItem) Item.CurrentPrice.
Item.ConvertedCurrentPrice [ attribute currencyID ]	CurrencyCodeType	Conditionally	Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType.
Item.Country	CountryCodeType	Always	Two-letter ISO 3166 country code to indicate the country where the item is located. Applicable values: See Country. IncludeSelector: Details. Also returned if IncludeSelector is not provided on input.
Item.CurrentPrice	AmountType (double)	Conditionally	The current price of the item, in the currency of the site on which the item was listed. That is, CurrentPrice is in the original listing currency. If the item is a multi-quantity listing, this is the price of one item. For competitive-bidding listings (Chinese and Dutch auctions), this is the current minimum bid price (if the listing has no bids) or the current high bid (if the listing has bids). (Compare to BuyItNowPrice). For Basic Fixed-Price (FixedPriceItem), Store Inventory (StoresFixedPrice), and Ad format (AdType) listings, this is the current fixed price. IncludeSelector: Details. See (GetSingleItem) Item.ConvertedCurrentPrice.
Item.CurrentPrice [ attribute currencyID ]	CurrencyCodeType	Conditionally	Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType.
Item.Description	string	Conditionally	The seller's description of the item, if any. This can include HTML markup and JavaScript. See string in Simple Schema Types. Some sellers don't specify their own listing description. Instead, they use a stock description from a catalog available through eBay. (GetSingleItem doesn't return this stock information.) Max length: 500000 (some sites may allow more, but the exact number may vary). IncludeSelector: Description, TextDescription.
Item.EndTime	dateTime	Always	Time stamp (in GMT) of when the listing is scheduled to end, or time stamp of the actual end time (if the item ended). In FindItemsAdvanced and FindItems, for StoresFixedPrice items which are "Good Till Canceled," this value is 5 minutes later than the actual end time of the item. The discrepancy is intended to facilitate renewal every 30 days of such items' end times. IncludeSelector: Description, Details, ItemSpecifics, ShippingCosts. Also returned if IncludeSelector is not provided on input.
Item.GalleryURL	anyURI	Conditionally	URL for a picture used as the Gallery thumbnail, if any. The image uses one of the following graphics formats: JPEG, BMP, TIF, or GIF. Only returned if the seller chose to show a gallery image. IncludeSelector: Description, Details, ItemSpecifics, ShippingCosts. Also returned if IncludeSelector is not provided on input.
Item.HighBidder	SimpleUserType	Conditionally	For single-item (Quantity = 1) auction listings (Chinese type) that have ended and have a winning bidder, indicates the user who is the current high bidder. For single-item basic fixed price (FixedPriceItem) or Store Inventory (StoresFixedPrice) listings that have ended, indicates the user who purchased the item. Not returned for auctions that have received no bids; fixed price and Store Inventory listings that are still active; or any multi-item (Quantity > 1) listings (Dutch, FixedPriceItem, StoresFixedPrice). IncludeSelector: Details. See Item.Quantity.
Item.HighBidder .FeedbackPrivate	boolean	Always	Indicates whether the user has chosen to make their feedback score and feedback details private (hidden from other users). Note that the percentage of positive feedback can still be returned, even if other feedback details are private. If a bidder's user information is made anonymous, the value -99 is returned. IncludeSelector: Details.
Item.HighBidder .FeedbackRatingStar	FeedbackRatingStarCodeType	Always	Visual indicator of user's feedback score. Applicable values: • Blue (out) Blue Star, feedback score 50-99. • CustomCode (out) Placeholder value. See token. • Green (out) Green Star, feedback score 5,000-9,999. • None (out) No graphic displayed, feedback score 0-9. • Purple (out) Purple Star, feedback score 500-999. • PurpleShooting (out) Purple Shooting Star, feedback score 50,000-99,999. • Red (out) Red Star, feedback score 1,000-4,999 • RedShooting (out) Red Shooting Star, feedback score 100,000 and above. • Turquoise (out) Turquoise Star, feedback score 100-499. • TurquoiseShooting (out) Turquoise Shooting Star, feedback score 25,000-49,999. • Yellow (out) Yellow Star, feedback score 10-49. • YellowShooting (out) Yellow Shooting Star, feedback score 10,000-24,999. IncludeSelector: Details.
Item.HighBidder.FeedbackScore	int	Conditionally	The aggregate feedback score of a user. A user's feedback score is the net positive feedback minus the net negative feedback left for the user. Feedback scores are a quantitative expression of the desirability of dealing with a user as a buyer or a seller in transactions. Each transaction can result in one feedback entry for a given user. (The buyer can leave feedback for the seller, and the seller can leave feedback for the buyer.) That one feedback can be positive, negative, or neutral. The aggregate feedback score of a user represents that user's overall feedback score (referred to as a "feedback rating" on the eBay site). If the user has chosen to make their feedback private, then FeedbackScore is not returned and FeedbackPrivate is returned with a value of true. If a bidder's user information is made anonymous, the value -99 is returned. IncludeSelector: Details.
Item.HighBidder.UserAnonymized	boolean	Conditionally	Indicates whether eBay has made this user's information anonymous. This occurs when the listing prices (reserve, current, or Buy It Now) reach or exceed a certain amount (such as $200 USD at the time of this writing). If true, certain other fields about this user are not returned, or their values include no identifying characteristics. (The rules are explained in the description of each field.) If false, all user-specific fields contain the user's actual data. IncludeSelector: Details.
Item.HighBidder.UserID	string	Always	The user's eBay user ID. A unique value. If a bidder's user information is made anonymous, the real ID value will be replaced with the value "Bidder X" where X is a number indicating the order of that user's first bid. For example, if the user was the third bidder, UserID = Bidder 3. Note that the anonymous bidder ID stays the same for a given auction, but is different for different auctions. For example, a bidder who is the third and then the seventh bidder in an auction will be listed for both bids as "Bidder 3". However, if that same bidder is the first bidder on a different auction, the bidder will be listed for that auction as "Bidder 1", not "Bidder 3". IncludeSelector: Details.
Item.HitCount	long	Conditionally	The number of times the listing's View Item page has been viewed (as determined by eBay). Only returned if the seller has chosen to include a hit counter in the listing, and if the seller has also chosen to make the listing's hit count publicly visible. This field is retrieved asynchronously. If you believe the item has a publicly visible hit count, but this field is not returned, retry the call. IncludeSelector: Details.
Item.ItemID	string	Always	The ID that uniquely identifies the item listing. eBay generates this ID when an item is listed. This ID is unique across all eBay sites. Max length: 19 (Note: The eBay database specifies 38. Currently, Item IDs are usually 9 to 12 digits). IncludeSelector: Description, Details, ItemSpecifics, ShippingCosts. Also returned if IncludeSelector is not provided on input.
Item.ItemSpecifics	NameValueListArrayType	Conditionally	Category-specific fields that the seller added to describe the listing. The names of these fields are different for items in different categories, so they're returned in a generic name/value structure. The field names are usually very well known within the category. For example, a book's item specifics might include a field like Publication Year=2007 (where Publication Year is returned in Name, and 2007 is returned in Value), and a field like Format=Hardcover. But a car's item specifics would be different from a book's, with fields like Make=Toyota and Model=Prius. And a ticket's item specifics would be different from those of books and cars, with fields like EventType=Concerts and Venue=The Fillmore. One of the most common uses for item specifics is the item condition. Only contains data if the listing includes Item Specifics. IncludeSelector: ItemSpecifics.
Item.ItemSpecifics .NameValueList	NameValueListType (repeatable)	Conditionally	This list is an array of Item Specifics, which are category-specific fields that the seller added to describe the listing. The names of these fields are different for items in different categories, so they're returned in a generic name/value structure. For example, Item Specifics for a car might include a field like Make=Toyota (where Make is returned in Name, and Toyota is returned in Value) and Model=Prius (where Model is returned in Name, and Prius is returned in Value). For FindProducts, this can also be an Item Specific that is defined for a product. That is, Item Specifics can be returned both for items and products in FindProducts. IncludeSelector: ItemSpecifics.
Item.ItemSpecifics .NameValueList.Name	string	Conditionally	The name of the item specific. This field is always returned for each item specific that is returned (if any). However if the seller didn't select a value for the item specific, we suggest you don't show the name (to avoid confusing users). For the item condition, this usually includes the word "Condition" for eBay US, UK, Australia, and India listings; and "Artikelzustand" for eBay Germany, Austria, and Switzerland listings. The Name fields in return policy item specifics (if any) usually include the word "return", "refund", and/or "warranty" for eBay US, Canada, UK, Australia, and India listings; and "Rucknahme", "return", and/or "refund" for eBay Germany, Austria, and Switzerland listings. Note: Ignore item specifics with SIFFTAS in the name. These are for internal use by eBay and aren't meaningful to users. IncludeSelector: ItemSpecifics.
Item.ItemSpecifics .NameValueList.Value	string (repeatable)	Conditionally	A value for the item specific. In GetSingleItem, this field is always returned for each item specific that is returned (if any). However, if the seller didn't select a value for the item specific, this field may return empty, or it may return a value like "-", "Not Selected", or "Unspecified" (or the equivalent in the language of the site). For the item condition, this usually includes the word "New" or "Used" for eBay US, UK, Australia, and India listings; and "Neu" or "Gebraucht" for eBay Germany, Austria, and Switzerland listings. IncludeSelector: ItemSpecifics.
Item.ListingStatus	ListingStatusCodeType	Always	Specifies a listing's status in eBay's processing workflow. If an item's EndTime is in the past, but no details about the buyer or high bidder are shown (and the user is not anonymous), use this listing status information to determine whether eBay has finished processing the listing. Applicable values: • Active (out) The listing is still live, or it has recently ended but eBay has not completed processing the listing (e.g., we're still determining the high bidder). A multi-item listing is considered active until all items have winning bids or purchases or the listing's end time has passed. (That is, if the listing has a Quantity of 10, the sale of 1 of those items doesn't end the listing.) If the listing has ended but this Active status is returned, please allow several minutes for eBay to finish processing the listing. • Completed (out) The listing has ended and eBay has completed processing of the sale (if any), such as determining the high bidder. You can think of Completed and Ended as essentially equivalent. (The difference is only meaningful to the seller of the item, as Completed indicates whether eBay has finished calculating certain selling fees.) • CustomCode (out) Placeholder value. See token. • Ended (out) The listing has ended and eBay has completed processing of the sale (if any), such as determining the high bidder. IncludeSelector: Description, Details, ItemSpecifics, ShippingCosts. Also returned if IncludeSelector is not provided on input.
Item.ListingType	ListingTypeCodeType	Always	The format of the listing, such as online auction, fixed price, or advertisement format. Applicable values: • AdType (out) Advertisement to solicit inquiries on listings such as real estate. Permits no bidding on that item, service, or property. To express interest, a buyer fills out a contact form that eBay forwards to the the seller as a lead. This format does not enable buyers and sellers to transact online through eBay, and eBay Feedback is not available for ad format listings. • Chinese (out) Single-quantity online auction format. A Chinese auction has a Quantity of 1. Buyers engage in competitive bidding, although Buy It Now may be offered as long as no bids have been placed. Online auctions are listed on eBay.com, and they are also listed in the seller's eBay Store if the seller is a Store owner. • CustomCode (out) Placeholder value. See token. • Dutch (out) Multiple-quantity online auction format. A Dutch auction has a Quantity greater than 1. Buyers engage in competitive bidding. Some sites also offer Buy It Now for Dutch auctions. Online auctions are listed on eBay.com, and they are also listed in the seller's eBay Store if the seller is a Store owner. • Express (out) For Germany only: eBay Express-only format (item is listed only on eBay Express Germany, not on eBay). • FixedPriceItem (out) A basic fixed-price listing with a Quantity of 1 or more. Allows no auction-style bidding. Also known as Buy It Now Only on some sites (not to be confused with the BuyItNow option that is available for Chinese auctions). Fixed-price listings appear on eBay.com, and they are also listed in the seller's eBay Store if the seller is a Store owner. • LeadGeneration (out) Lead Generation format (advertisement-style listing to solicit inquiries or offers, no bidding or fixed price, listed on eBay). • Live (out) Live auction, on-site auction that can include non-eBay bidders. Live auctions are listed on the eBay Live Auctions site, in live auction categories. They can also appear on eBay if the seller lists the lot in a secondary category that is an eBay category. • PersonalOffer (out) Second chance offer made to a non-winning bidder on an ended listing. A seller can make an offer to a non-winning bidder when either the winning bidder has failed to pay for an item or the seller has a duplicate of the item. Second-chance offer items are on eBay, but they do not appear when browsing or searching listings. You need to already know the item ID in order to retrieve a second-chance offer. • StoresFixedPrice (out) A fixed-price format for eBay Store sellers. Store Inventory listings appear after other listings in regular browse and search item lists on eBay. They have a lower Insertion Fee and longer listing durations. Only specified by sellers who have an eBay Store. Store Inventory listings are listed on eBay.com, and they are also listed in the seller's eBay Store. • Unknown (out) Unknown auction type. (This is not normally used.) (Not all values in ListingTypeCodeType apply to this field.) IncludeSelector: Description, Details, ItemSpecifics, ShippingCosts. Also returned if IncludeSelector is not provided on input.
Item.Location	string	Conditionally	Physical location of the item, as specified by the seller. (This gives a general indication of where the item will be shipped or delivered from.) IncludeSelector: Details. Also returned if IncludeSelector is not provided on input.
Item.MinimumToBid	AmountType (double)	Conditionally	Smallest amount the next bid on the item can be. Returns same value as Item.StartPrice (if no bids have yet been placed) or CurrentPrice plus BidIncrement (if at least one bid has been placed). Only applicable to Chinese and Dutch auction listings. Returns null for basic Fixed Price (FixedPriceItem),Store Inventory (StoresFixedPrice), and Ad type listings. IncludeSelector: Details.
Item.MinimumToBid [ attribute currencyID ]	CurrencyCodeType	Conditionally	Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType.
Item.PaymentAllowedSite	SiteCodeType (repeatable)	Conditionally	Enables you to view the sites on which an item can be purchased, based on the payment methods offered for the item. Applicable values: See PaymentAllowedSite. IncludeSelector: Details.
Item.PaymentMethods	BuyerPaymentMethodCodeType (repeatable)	Conditionally	Identifies the payment method (such as PayPal) the seller will accept when the buyer pays for the item. Note: If the seller only accepts PayPal, the buyer can still pay with a credit card. PayPal supports major credit cards. Payment methods are not applicable to eBay Real Estate advertisement listings, or other Classified Ad format listings. Applicable values: See PaymentMethods. IncludeSelector: Details.
Item.PictureURL	anyURI (repeatable)	Conditionally	Contains the URL for an image associated with the item, if any. Only returned if the seller chose to include at least one picture in the listing. (This doesn't return URLs of pictures that the seller specified via HTML IMG tags in Description.) Items listed the main eBay site can have a maximum of 12 picture URLs hosted by eBay Picture Services or a maximum of 6 picture URLs hosted by a third party (such as the seller or a photo site). On the US eBay Motors site (for all vehicle listings), and on the eBay Canada Motors site, a listing can have up to 24 picture URLs. eBay uses the seller's first picture at the top of the listing's View Item page. Max length: 150. IncludeSelector: Description, Details, ItemSpecifics, ShippingCosts. Also returned if IncludeSelector is not provided on input.
Item.PostalCode	string	Conditionally	Postal code indicating the physical location of the item, as specified by the seller. (This gives a general indication of where the item will be shipped or delivered from.) IncludeSelector: Details.
Item.PrimaryCategoryID	string	Always	Numeric ID of the first (or only) category in which the item is listed. (Listings can appear in more than one category.) Note: Currently, GetSingleItem does not return a listing's secondary category, if any. IncludeSelector: Description, Details, ItemSpecifics, ShippingCosts. Also returned if IncludeSelector is not provided on input.
Item.PrimaryCategoryIDPath	string	Always	The fully qualified ID breadcrumb (path) of the first category. For example, if the primary category ID is 45678, and its parent category's ID is 123, the breadcrumb (path) would be 123:45678. IncludeSelector: Details.
Item.PrimaryCategoryName	string	Always	Display name of the first (or only) category in which the item is listed. This is a fully qualified category breadcrumb (e.g., Computers & Networking:Laptops, Notebooks). IncludeSelector: Description, Details, ItemSpecifics, ShippingCosts. Also returned if IncludeSelector is not provided on input.
Item.ProductID	ProductIDType (string)	Conditionally	A prototype description of a well-known type of item, such as a popular book. When returned for GetSingleItem, is always of type Reference, and serves as a global reference ID for an eBay catalog product. When used as input, retrieves product details for one specific product. Specify the ID as a string, and use the type attribute to indicate the nature of the ID you are specifying. The request requires either QueryKeywords or ProductID, but these fields cannot be used together. Max length: 4000. IncludeSelector: Details.
Item.Quantity	int	Conditionally	The number of items the seller is offering in the listing. (Subtract Item.QuantitySold from this value to calculate the number of items currently available for sale.) If an online auction (with competitive bidding) has a Quantity of 1, it's a Chinese auction. If Quantity is greater than 1,it's a Dutch auction. Basic fixed-price and Store Inventory listings can have a Quantity of 1 or more. The listing's current or Buy It Now price is the price of 1 item in the listing. Note: A seller can also offer multiple items for sale with a single price for all the items. For example, instead of listing 10 lightbulbs for US 2.00 each, they might list 10 lightbulbs for USD 20.00 (where you have to buy all 10). This is called a "lot". If the listing includes a lot (or multiple lots), Quantity does not specify the lot size; it only reflects how many lots are being sold. For example, if the listing includes 5 lots of 10 lightbulbs each, Quantity would be 5. (GetSingleItem does not return information about lot sizes.) IncludeSelector: Details. See Item.ListingType.
Item.QuantitySold	int	Always	Number of items purchased so far from this listing. (Subtract this value from Item.Quantity to calculate the number of items currently available for sale.) IncludeSelector: Details.
Item.ReserveMet	boolean	Conditionally	Indicates whether any bids on this item are greater than the seller's reserve price for the listing (if any). A reserve is the lowest price at which the seller is willing to sell the item. The reserve price is higher than the listing's opening bid (minimum bid) and lower than the Buy It Now price, if any. (The reserve price is only known to the seller.) Some sellers don't set a reserve at all. If a listing does have a reserve price, the highest bidder will only win the item if their bid is also above that price. Only returned for online auctions that have a reserve price. (Fixed price, Store Inventory, and classified ad listings don't have reserve prices.) IncludeSelector: Details.
Item.ReturnPolicy	ReturnPolicyType	Conditionally	If a seller specified return policy details, then this container has fields with those details. The fields that can be returned in this container vary by site. IncludeSelector: Details.
Item.ReturnPolicy.Description	string	Conditionally	A description of the return policy for the item. IncludeSelector: Details.
Item.ReturnPolicy.EAN	string	Conditionally	Contains the EAN. IncludeSelector: Details.
Item.ReturnPolicy.Refund	string	Conditionally	Specifies how a refund will be made, e.g. as an exchange. IncludeSelector: Details.
Item.ReturnPolicy .ReturnsAccepted	string	Conditionally	Information about returns accepted. IncludeSelector: Details.
Item.ReturnPolicy .ReturnsWithin	string	Conditionally	Specifies the length of time

eBay Shopping API Call Reference Version 595

Best Practices

Refreshing Item Data

Getting Shipping Details

Getting an Item from a Different eBay Site

More Tips

eBay Shopping API
Call Reference Version 595