eBay Shopping API897

GetItemStatus

This call retrieves item status information for a list of up to 10 specified ItemIDs.

Usage Details

The item limit is set to 10 for this call to take advantage of the increased performance of the Shopping API.

Some common uses of GetItemStatus include buyers who want to find the latest status for a watch list or bid list, or sellers who want to find out the status of items that they have up for bid. If a seller what to find out the status of more than 10 items, they can use the GetItemTransactions call in the Trading API.

Only fields that are relevant to status are returned.



Back to top

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

See also Samples.

<?xml version="1.0" encoding="utf-8"?>
<GetItemStatusRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Input Fields -->
  <ItemID> string </ItemID>
  <!-- ... more ItemID values allowed here ... -->
  <!-- Standard Input Fields -->
  <MessageID> string </MessageID>
</GetItemStatusRequest>
Argument Type Occurrence Meaning
Call-specific Input Fields [Jump to standard fields]
ItemID string Required,
repeatable: [1..*]
The item ID that uniquely identifies the item listing for which to retrieve the data. You can provide a maximum of 20 ItemIDs. Use a comma to separate ItemIDs.
Max length: 19 (Note: The eBay database specifies 38. However, Item IDs are usually 9 to 12 digits).
Standard Input 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.



Back to top

Output

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.

<?xml version="1.0" encoding="utf-8"?>
<GetItemStatusResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Output Fields -->
  <Item> SimpleItemType
    <BidCount> int </BidCount>
    <BuyItNowAvailable> boolean </BuyItNowAvailable>
    <ConvertedCurrentPrice currencyID="CurrencyCodeType"> AmountType (double) </ConvertedCurrentPrice>
    <EndTime> dateTime </EndTime>
    <HighBidder> SimpleUserType
      <FeedbackPrivate> boolean </FeedbackPrivate>
      <FeedbackRatingStar> FeedbackRatingStarCodeType </FeedbackRatingStar>
      <FeedbackScore> int </FeedbackScore>
      <UserID> string </UserID>
    </HighBidder>
    <ItemID> string </ItemID>
    <ListingStatus> ListingStatusCodeType </ListingStatus>
    <ReserveMet> boolean </ReserveMet>
    <TimeLeft> duration </TimeLeft>
  </Item>
  <!-- ... more Item nodes allowed here ... -->
  <!-- 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 ... -->
  <Timestamp> dateTime </Timestamp>
  <Version> string </Version>
</GetItemStatusResponse>
Return Value Type Occurrence Meaning
Call-specific Output Fields [Jump to standard fields]
Item SimpleItemType Always,
repeatable: [1..*]
Collection of Item status objects in an SimpleItemArrayType object, that can include zero, one, or multiple ItemType objects.
Item.BidCount int Always The number of bids that have been placed on the item.

On most sites, the Buy It Now Option becomes unavailable once an auction has a valid bid. Note that the bid must be above any reserve price.

FindPopularItems: For fixed-price listings, the BidCount value is the total number of items purchased so far (in the listing's lifetime).
Item.BuyItNowAvailable boolean Conditionally Indicates whether the item has an active Buy It Now option. On most sites, the Buy It Now option is disabled once a valid bid for the item has been accepted. To see if the item was listed with a Buy It Now option, see if the response includes Item.BuyItNowPrice.

This field is returned only if the value is true.
Item.ConvertedCurrentPrice AmountType (double) Always 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.

Some eBay sites also support multi-item Buy It Now auctions, where you can buy multiple items from the same listing at a fixed price. See Item.BuyItNowAvailable.

For fixed-price (FixedPriceItem) listings, see CurrentPrice or ConvertedCurrentPrice instead.

Returned only if an item was listed with a Buy It Now option.

For active items, refresh this value every 24 hours to pick up the current conversion rates (if this value has been converted).

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.ConvertedCurrentPrice
  [ attribute currencyID ]
CurrencyCodeType Always 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.

Some eBay sites also support multi-item Buy It Now auctions, where you can buy multiple items from the same listing at a fixed price. See Item.BuyItNowAvailable.

For fixed-price (FixedPriceItem) listings, see CurrentPrice or ConvertedCurrentPrice instead.

Returned only if an item was listed with a Buy It Now option.

For active items, refresh this value every 24 hours to pick up the current conversion rates (if this value has been converted).

For a list of possible enumeration values, see CurrencyCodeType.
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).

See (GetSingleItem) Item.Variations.

Item.HighBidder SimpleUserType Conditionally The high bidder for competitive-bidding auctions that have ended and have a winning bidder. This indicates the user who purchased the item.

Not returned for auctions that have received no bids, or for fixed price listings that are still active.

See Item.Quantity.

Item.HighBidder
  .FeedbackPrivate
boolean Conditionally 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.
Item.HighBidder
  .FeedbackRatingStar
FeedbackRatingStarCodeType Conditionally 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.
GreenShooting
(out) Green Shooting Star, feedback score 500,000-900,000.
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-499,999.
SilverShooting
(out) Silver Shooting Star, feedback score 1,000,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.

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.
Item.HighBidder.UserID string Conditionally The user's unique eBay user ID.

When reporting UserIDs in bidding situations (such was when listing the high bidder in an auction), eBay replaces the UserID value with an anonymous bidder name value, such as "a***o".
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).

See (GetSingleItem) Item.Variations.

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.

Item.ReserveMet boolean Always 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.)
Item.TimeLeft duration Always Time left before the listing ends. The duration is represented in the ISO 8601 duration format (PnYnMnDTnHnMnS). For ended listings, the time left is PT0S (zero seconds).

See (GetSingleItem) Item.Variations.

Standard Output 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 Conditionally,
repeatable: [0..*]
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 Conditionally,
repeatable: [0..*]
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 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.
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
    Checklist for Going Live for more information see the eBay Features 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 Schema Versioning Strategy.



Back to top

Detail Controls


DetailLevel

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

Back to top

Samples

New to making API calls? Please see Making an API 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.

Sample: Basic Call

Retrieves status for all items in a specified ItemID list.

Input

GetItemStatus takes a SimpleItemArrayType object that specifies a list of ItemID values. The list can include zero, one, or multiple ItemType objects, depending on whether you want to retrieve a single-item or multiple-item listing.

This example retreives the status for all items in the specified list of ItemID values.

URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML, 
specify a different value for responseencoding.
http://open.api.ebay.com/shopping?
   callname=GetItemStatus&
   responseencoding=XML&
   appid=youAppID&
   siteid=0&
   version=515&
   ItemID=180126682091,230139965209,300118131654,300118131865,300118132027

   Here is the same input in XML format (HTTP POST). Note that this does not include standard values.

XML format (HTTP POST). Also available are the .txt version of this XML and the SOAP equivalent.

<?xml version="1.0" encoding="utf-8"?>
   <GetItemStatusRequest xmlns="urn:ebay:apis:eBLBaseComponents">
      <ItemID>180126682091</ItemID>
      <ItemID>230139965209</ItemID>
      <ItemID>300118131654</ItemID>
      <ItemID>300118131865</ItemID>
      <ItemID>300118132027</ItemID>
   </GetItemStatusRequest>
  

Output

This sample returns ItemID, BuyItNowAvailable, EndTime, BidCount, ConvertedCurrentPrice, ListingStatus, and Timeleft for each item in the request.

XML format. Also available are the .txt version of this XML and the SOAP and JSON equivalent.

  <?xml version="1.0" encoding="UTF-8" ?> 
  <GetItemStatusResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2007-06-07T20:07:44.056Z</Timestamp> 
  <Ack>Success</Ack> 
  <Build>e515_core_APILW_4756831_R1</Build> 
  <Version>515</Version> 
     <Item>
    <ItemID>180126682091</ItemID> 
    <EndTime>2007-06-12T18:51:06.000Z</EndTime> 
    <BidCount>1</BidCount> 
    <ConvertedCurrentPrice currencyID="USD">0.88</ConvertedCurrentPrice> 
    <ListingStatus>Active</ListingStatus> 
    <TimeLeft>P4DT22H43M23S</TimeLeft> 
     </Item>
     <Item>
       <ItemID>230139965209</ItemID> 
    <EndTime>2007-06-14T02:30:00.000Z</EndTime> 
    <BidCount>2</BidCount> 
    <ConvertedCurrentPrice currencyID="USD">1.25</ConvertedCurrentPrice> 
    <ListingStatus>Active</ListingStatus> 
    <TimeLeft>P6DT6H22M17S</TimeLeft> 
     </Item>
     <Item>
    <ItemID>300118131654</ItemID> 
    <EndTime>2007-06-07T16:50:46.000Z</EndTime> 
    <BidCount>0</BidCount> 
    <ConvertedCurrentPrice currencyID="USD">34.99</ConvertedCurrentPrice> 
    <ListingStatus>Completed</ListingStatus> 
     </Item>
     <Item>
    <ItemID>300118131865</ItemID> 
    <EndTime>2007-06-07T16:51:30.000Z</EndTime> 
    <BidCount>0</BidCount> 
    <ConvertedCurrentPrice currencyID="USD">34.99</ConvertedCurrentPrice> 
    <ListingStatus>Completed</ListingStatus> 
     </Item>
     <Item>
    <ItemID>300118132027</ItemID> 
    <EndTime>2007-06-07T03:25:49.000Z</EndTime> 
    <BidCount>0</BidCount> 
    <ConvertedCurrentPrice currencyID="USD">34.99</ConvertedCurrentPrice> 
    <ListingStatus>Completed</ListingStatus> 
    </Item>
  </GetItemStatusResponse>



Back to top

Change History

Version Description
699
2010-12-08
  • Item.ConvertedBuyItNowPrice (doc change): Removed the field from this call, as a documentation correction.
695
2010-11-10
  • Item.ConvertedCurrentPrice (doc change): Added the field to this call, as a documentation correction.
535
2007-10-17
  • (doc change) Added call limit of 10 items to usage information.
515
2007-06-10
  • (added) New call.

Back to top

User-Contributed Notes