eBay Shopping APIVersion 1293
 

GetItemStatus

Note: All calls in the Shopping API have been deprecated and will be decommissioned on February 5, 2025. An alternative to this API is the Browse API, which also has advanced search capabilities.

Note: Developers using Shopping API calls must authenticate with an OAuth application access token in the HTTP header X-EBAY-API-IAF-TOKEN and use OAuth application access tokens with a scope that includes https://api.ebay.com/oauth/api_scope. See the client credentials grant flow topic for more information on generating and managing OAuth application access tokens. See the Specifying OAuth scopes topic for more information on OAuth scopes.

This call retrieves the current status of up to 20 eBay listings.

The GetItemStatus call can be used by sellers and buyers who want to know the current status of any eBay listing. All retrieved listings will show listing status, fixed price (or highest bid price for auctions), and scheduled end time of listing. Other response fields are only relevant for auction listings and bidder data will only be returned to the seller of the auction listing.

Note that the amount of data that is returned in GetItemStatus is fairly limited. To retrieve more robust data for listings, sellers may want to consider using the GetMyeBaySelling call in the Trading API, and buyers may want to consider using the GetMyeBayBuying call in the Trading API.



Input Output Detail Controls Samples Change History

Input

See also Samples.

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

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

<?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..20]		 The unique identifier of the eBay listing to retrieve. You can retrieve the status of up to 20 listings per call, and a separate ItemID field is required for each listing.
Standard Input Fields  
MessageID string Optional If you pass a value into the MessageID field in a request, the same value is returned in CorrelationID field 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.



Input Output Detail Controls Samples Change History

Output

See also Samples.

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

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

<?xml version="1.0" encoding="utf-8"?>
<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..20]		 An Item container is returned for each ItemID value that was specified in the call request. One GetItemStatus call can retrieve up to 20 eBay listings.
Item.BidCount int Always This integer value indicates the number of bids that have been placed on an auction item. This field is only applicable to auction listings, but it is always returned for all listings, and its value will be '0' if bids are not applicable to the listing.
Item.BuyItNowAvailable boolean Conditionally This field is only returned if the Buy It Now feature is enabled and available on an active auction listing. This field is only returned if true. With the Buy It Now feature, interested buyers have the option of bypassing the auction procedure, and purchasing the item immediately at the price shown in the BuyItNowPrice field (or in the ConvertedBuyItNowPrice field for international buyers.

Once a qualifying bid is made on an auction listing, the Buy It Now feature ceases being an option to interested buyers, and the BuyItNowAvailable field will no longer be returned for the active auction listing.
Item.ConvertedCurrentPrice AmountType (double) Always In a fixed-price or classified ad listing, this price is the current price of the item, shown in the currency of the user's country. In an active auction listing, this field's value reflects the current bid price for the auction item, so any submitted bids must be above this value. If the Buy It Now feature is available for an auction item (look for BuyItNowAvailable field), the user will want to look at the ConvertedBuyItNowPrice field instead if that user is interested in skipping the auction process and buying that item immediately.

Note: If the user retrieves a multiple-variation listing, and the IncludeSelector filter is set to Variations, the ConvertedCurrentPrice field is still returned, but its value will reflect the lowest-priced item variation. So, if the multiple-variation listing has item variations priced from 7.99 to 12.99, the ConvertedCurrentPrice field's value will show '7.99'. If the price of all item variations are the same, the ConvertedCurrentPrice field value will be accurate, but it is recommended that the user scan down to individual Variation.StartPrice fields to get the accurate price for all item variations.

See:
    Item.BuyItNowAvailable
    Item.ConvertedBuyItNowPrice
    Item.Variations.Variation.StartPrice

Item.ConvertedCurrentPrice
  [ attribute currencyID ]		 CurrencyCodeType Always In a fixed-price or classified ad listing, this price is the current price of the item, shown in the currency of the user's country. In an active auction listing, this field's value reflects the current bid price for the auction item, so any submitted bids must be above this value. If the Buy It Now feature is available for an auction item (look for BuyItNowAvailable field), the user will want to look at the ConvertedBuyItNowPrice field instead if that user is interested in skipping the auction process and buying that item immediately.

Note: If the user retrieves a multiple-variation listing, and the IncludeSelector filter is set to Variations, the ConvertedCurrentPrice field is still returned, but its value will reflect the lowest-priced item variation. So, if the multiple-variation listing has item variations priced from 7.99 to 12.99, the ConvertedCurrentPrice field's value will show '7.99'. If the price of all item variations are the same, the ConvertedCurrentPrice field value will be accurate, but it is recommended that the user scan down to individual Variation.StartPrice fields to get the accurate price for all item variations.

For a list of possible enumeration values, see CurrencyCodeType.
Item.EndTime dateTime Always For active listings, this timestamp indicates the date and time when the listing is scheduled to end, and for recently ended listings, this timestamp indicates the date and time when the listing actually ended.
Item.HighBidder SimpleUserType Conditionally This container provides a few details about the current high bidder for an active auction listing, or the winning bidder for a completed auction listing. This container is only returned for auction listings with at least one bid, and only if the IncludeSelector filter is included in the request and set to Details. The high bidder details include the bidder's eBay user ID and Feedback Score. For the GetItemStatus call, only the eBay user ID is returned.

Note: The eBay user ID and the Feedback data will actually be obfuscated to all users except for the owner (seller) of the listing, so essentially, the HighBidder container only has value to the seller of the listing.
Item.HighBidder
  .FeedbackPrivate 		boolean Conditionally This boolean value indicates whether or not the eBay user has chosen to make their Feedback Profile private in My eBay. A private Feedback Profile only means that individual Feedback comments are hidden, but other Feedback statistics will still be displayed, including the total Feedback score and the Positive Feedback Percentage.

Sellers on eBay marketplaces do not have the option of making their Feedback Profile private, and they will be blocked from listing if they try to list items with a private Feedback Profile.
Item.HighBidder
  .FeedbackRatingStar 		FeedbackRatingStarCodeType Conditionally This enumeration value indicates the eBay user's Feedback Rating Star. A different colored star is associated with each Feedback Score range. For more details on the Feedback Score ranges (and colored stars associated with each range), see FeedbackRatingStarCodeType.

Applicable values: See FeedbackRatingStar.
Code so that your app gracefully handles any future changes to this list.
Item.HighBidder.FeedbackScore int Conditionally The aggregate Feedback score of an eBay user. A user's Feedback score is determined by the total number of Positive Feedback ratings minus the total number of Negative Feedback ratings the user has received. Any Neutral Feedback ratings do not affect the Feedback Score.

A user's Feedback Score is a quantitative expression of the desirability of dealing with that user as a buyer or a seller. A buyer can leave Positive, Neutral, or Negative Feedback for the seller, but a seller can only leave Positive Feedback for the buyer.
Item.HighBidder.UserID string Conditionally The unique identifier of the eBay user. An eBay user ID is unique across all eBay marketplaces.

This field is generally always returned, but it may be masked depending on the situation. For example, if anyone other than the seller of the listing runs a GetItemStatus call on an active auction listing with one or or bids, the UserID value will be masked something like this - b***r.
Item.ItemID string Always The unique identifier of the eBay listing. This will be the same ItemID value that is passed into the call request.
Item.ListingStatus ListingStatusCodeType Always This enumeration value indicates the current status of the listing. The three different listing states are discussed below.

Applicable values:

Active
(out) This enumeration value indicates that the listing is still active. A multiple-quantity, fixed-price listing is considered active until the quantity available is '0', or the listing's scheduled end time has passed.
Completed
(out) This enumeration value indicates that the listing has ended and eBay has completed processing any sales/winning bids, and the calculation of the seller's Final Value Fee.
CustomCode
(out) This enumeration is reserved for future use.
Ended
(out) This enumeration value indicates that the listing has ended and eBay has completed processing any sales/winning bids. The next state after 'Ended' is 'Completed'.

Code so that your app gracefully handles any future changes to this list.
Item.ReserveMet boolean Conditionally This boolean field indicates if the current/highest bid price has matched or exceeded the price set as the Reserve Price by the seller. A Reserve Price is the lowest price at which the seller is willing to sell the item through an auction. If the highest bid does not meet or exceed the Reserve Price, the auction listing will end without a sale (winning bidder) when the scheduled end time is reached.

The Reserve Price must be higher than the starting bid price, but lower than the Buy It Now price (if one is set). This field is only applicable to auction listings, and only returned for auction listings if the seller has set a Reserve Price.
Item.TimeLeft duration Always The value in this field indicates the precise time left before the listing is scheduled to end. The format used in this field is the format defined in the ISO 8601 duration format standard. See the duration simple type definition for more information on syntax/notation used for this type.

This field is always returned, even if the listing is in the Completed state. A completed/ended listing will essentially have 0 seconds left, so the Completed value will be PT0S, which indicates '0 seconds' left.
Standard Output Fields  
Ack AckCodeType Always A token representing the application-level acknowledgement code that indicates the response status (e.g., success). The AckCodeType list specifies the possible values for the Ack field.

Applicable values:

CustomCode
(out) Reserved for internal or future use.
Failure
(out) This value indicates that the call request processing failed.
Success
(out) This value indicates that the call request was processed successfully without any issues.
Warning
(out) This value indicates that the call request was successful, but processing was not without any issues. These issues can be checked in the Errors container, that will also be returned when one or more known issues occur with the call request.

(Not all values in AckCodeType apply to this field.)

Code so that your app gracefully handles any future changes to this list.
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.

Code so that your app gracefully handles any future changes to this list.

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 This is the value of the request parameter noted in the ParamID attribute. So, if the ParamID value was ItemID, the value in this field would be the actual value of that ItemID.
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.

Code so that your app gracefully handles any future changes to this list.

See:
    Errors by Number
    Error Handling

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 version of the API call that eBay used to process the request.

Note: Note that some calls are not always updated with each WSDL release, so it is possible that version numbers will differ by API call.
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.



Input Output Detail Controls Samples Change History

Detail Controls


DetailLevel

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



Input Output Detail Controls Samples Change History

Samples

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 one or more specified item listings.

Input

GetItemStatus takes an array of ItemID values. The list can include one or more ItemID values.

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

URL format. See also the non-wrapped version of this URL. For results in a format other than XML, 
specify a different value for responseencoding.

https://open.api.ebay.com/shopping?
   callname=GetItemStatus&
   responseencoding=XML&
   siteid=0&
   version=967&
   ItemID=1**********1,2**********9,3**********4,3**********5,3**********7

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

XML format. Also available is the SOAP equivalent.

<?xml version="1.0" encoding="utf-8"?>
   <GetItemStatusRequest xmlns="urn:ebay:apis:eBLBaseComponents">
      <ItemID>1**********1</ItemID>
      <ItemID>2**********9</ItemID>
      <ItemID>3**********4</ItemID>
      <ItemID>3**********5</ItemID>
      <ItemID>3**********7</ItemID>
   </GetItemStatusRequest>

Output

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

XML format. Also available are the JSON and SOAP equivalents.

  <?xml version="1.0" encoding="UTF-8" ?>
  <GetItemStatusResponse xmlns="urn:ebay:apis:eBLBaseComponents">
    <Timestamp>2016-06-07T20:07:44.056Z</Timestamp>
    <Ack>Success</Ack>
    <Build>e967_core_APILW_4756831_R1</Build>
    <Version>967</Version>
    <Item>
      <ItemID>1**********1</ItemID>
      <EndTime>2016-06-12T18:51:06.000Z</EndTime>
      <BidCount>1</BidCount>
      <ConvertedCurrentPrice currencyID="USD">0.88</ConvertedCurrentPrice>
      <ListingStatus>Active</ListingStatus>
      <TimeLeft>P4DT22H43M23S</TimeLeft>
    </Item>
    <Item>
       <ItemID>2**********9</ItemID>
      <EndTime>2016-06-14T02:30:00.000Z</EndTime>
      <BidCount>2</BidCount>
      <ConvertedCurrentPrice currencyID="USD">1.25</ConvertedCurrentPrice>
      <ListingStatus>Active</ListingStatus>
      <TimeLeft>P6DT6H22M17S</TimeLeft>
    </Item>
    <Item>
      <ItemID>3**********4</ItemID>
      <EndTime>2016-06-07T16:50:46.000Z</EndTime>
      <BidCount>0</BidCount>
      <ConvertedCurrentPrice currencyID="USD">34.99</ConvertedCurrentPrice>
      <ListingStatus>Completed</ListingStatus>
    </Item>
    <Item>
      <ItemID>3**********5</ItemID>
      <EndTime>2016-06-07T16:51:30.000Z</EndTime>
      <BidCount>0</BidCount>
      <ConvertedCurrentPrice currencyID="USD">34.99</ConvertedCurrentPrice>
      <ListingStatus>Completed</ListingStatus>
    </Item>
    <Item>
      <ItemID>3**********7</ItemID>
      <EndTime>2016-06-07T03:25:49.000Z</EndTime>
      <BidCount>0</BidCount>
      <ConvertedCurrentPrice currencyID="USD">34.99</ConvertedCurrentPrice>
      <ListingStatus>Completed</ListingStatus>
     </Item>
  </GetItemStatusResponse>



Input Output Detail Controls Samples Change History

Change History

Change Date Description
1119
2019-08-02
  • GetItemStatus (modified): Shopping API endpoint updated to support 'https' protocol. So, the following production endpoint should be used for all Shopping API calls: https://open.api.ebay.com/shopping. The http://open.api.ebay.com/shopping endpoint will still be supported for the time being, but is subject to be wired off.
0699
2010-12-08
  • Item.ConvertedBuyItNowPrice (doc change): Removed the field from this call, as a documentation correction.
0695
2010-11-10
  • Item.ConvertedCurrentPrice (doc change): Added the field to this call, as a documentation correction.
0535
2007-10-17
  • (doc change) Added call limit of 10 items to usage information.
0515
2007-06-10
  • (added) New call.