Retrieving Items

This chapter discusses the means for retrieving the data for item listings.

Subtopics

Browsing a Seller's Items

Retrieving the Data for One Item

Displaying Discount Pricing Information to Buyers

An application can retrieve data from the eBay site, to be displayed in the application's particular user interface or otherwise processed by the application. Items can be retrieved in whole groups (such as a list of the items a particular seller has listed). This replicates similar functionality on the eBay site. Items can also be retrieved one at a time, which is analogous to the View Item page on the eBay site.

One reason an application returns the data for an item or group of items is to display the item data in a visual format. The application's end user could then see the data and use the information as the basis for taking some action, such as a seller revising the item or a buyer making a bid on the item.

Another reason for retrieving item data is the programmatic processing of item data outside the context of a user interface or human intervention. For example, an application could retrieve a list of the items for a particular seller for the purpose of assessing bidding activity, only alerting the seller should a predetermined condition exist (like the end of the auction is near and there is a current high bidder).

Applications retrieve whole lists of items for a particular seller using GetSellerList. Retrieving the data for just a single item is done with GetItem. Most often it is more economical to use GetSellerList to retrieve a list of items and operate on them than it is to use GetItem multiple times. Doing this saves on the number of API calls made by an application (which are limited on an hourly, daily, and monthly basis). It also reduces total online time spent communicating and interacting with the eBay site.

For information on GetSellerList, including executing the call and business logic, see GetSellerList. For information on GetItem, see GetItem.

Browsing a Seller's Items

To retrieve a list of the items listed by a particular seller, use GetSellerList.

GetSellerList Call Reference

https://developer.ebay.com/DevZone/XML/docs/Reference/eBay/GetSellerList.html

In all calls, at least one date-range filter must be specified.

You can specify a DetailLevel to control the response data. If you set a DetailLevel, you must set pagination values.Specify the eBay user ID for the seller whose item's will be returned. This input is optional. If it is not specified, the user making the request is considered to be the seller whose items are returned.

The number of items that could be returned for a given seller is potentially large. To reduce the number of items returned, use date-based filter inputs. These filter the data based on when the items started, when the items ended, or when the items were last modified. Applications use this filtering to limit the items to just those of interest in the context of a given operation. For example, if the context calls for retrieving just the items that end on a particular day, the application should not filter for all the items ending within a given month.

Date-based filters work in pairs, delineating a date range described by the earliest (oldest) date of interest and a the latest (most recent) date of interest. For example, if you are retrieving the items that end on a particular day, the earliest date in the range might be one second after midnight on the morning of interest, and no items that ended prior to that date would be of interest.

The latest date in the range might be midnight that night, and no items that ended after that date would be of interest. When one filter input is used, the other matching filter element must also be used (the application must always specify both the oldest date and the most recent date for a filtering date range). For example, if EndTimeFrom is specified (because the filtering date range is based on the end date) then EndTimeTo must also be specified. At least one date-range filter must be specified. Multiple date-range filters may be used per call. For instance, a single call can return the items ending within a date range (one filter) plus those that started in a specified date range (a second filter).

Date-based filters are individually optional, but at least one must be specified (applicable to all detail levels).

Another way to reduce the number of items returned in any single call is through pagination. Pagination breaks the total data set down into smaller chunks that might be easier for the application to use.

If zero items would be returned, no "Invalid page number" error will be returned.

For example, if there are 100 items for a seller meeting other selection criteria for the call, the application could make one call retrieving all 100 items or ten calls that each retrieve 10 items (ten pages of ten items each).

Where the GetSellerList inputs are concerned, pagination is controlled by specifying the number of items to return in each page of data (i.e., for each call) and the page number to return. The first call would return page 1 of the seller's items. Data in the call's result set indicate whether there are additional items to retrieve and how many. The application can use that information to determine whether additional calls need to be made and, based on the page size (the number of items per page) how many additional calls need to be made for all of the items to be retrieved. If additional calls are needed, each subsequent call specifies an incrementally higher page number to retrieve each succeeding page of items. If items per page and page number are not specified for the call, no pagination takes place and the call attempts to retrieve the items as a single page of data.

Pagination is required if a detail level is specified. Only by using the smallest result set (no detail level specified) can the call be made without pagination—regardless of how many items would be returned.

The items retrieved using GetSellerList can optionally be sorted, based on the listing end dates of the returned items. It returns the items the seller has listed.

There is one ItemType object for each item listed by the specified seller and meeting the input filtering criteria. Also returned are indicators of how many items are returned and whether there are other items that could be returned (additional items meeting the criteria that require additional calls to retrieve). The result set also contains the page number for the data returned, the number of items being returned per page, and the total number of pages of items meeting the selection criteria.

The application needs to traverse this item array to visit each of the ItemType objects it contains and inspect its properties.

When a listing includes catalog product details and the seller has chosen to include additional stock summary information in the listing, the Description field is optional. This means items returned by GetSellerList (and other item-retrieval calls) are not guaranteed to contain a value in the Description field. See Pre-filling Item Specifics with Product Details for more information about listing with catalog product details.

Retrieving the Data for One Item

To retrieve the data for a single item, use GetItem. Doing this involves three general steps: setting up the execution environment, specifying the data to return (based on the item ID), and making the API call.

Retrieving the data for a single item entails specifying the item ID for the item to return.

GetItem returns the data for one item. The result set consists of one ItemType object, which contains the item's data. See the GetItem documentation in the eBay Trading API Reference for details.

GetItem Call Reference

https://developer.ebay.com/DevZone/XML/docs/Reference/eBay/GetItem.html

Retrieving an Item with Item Specifics and/or Product Data

If a listing includes Item Specifics, the Item Specifics will be returned when you execute GetItem with the ReturnAll or ItemReturnAttributes detail level. Similarly, if the listing includes catalog product details, the product details will be returned with these detail levels.

When you list in certain categories (or, more specifically, certain characteristics sets), GetItem may return additional Item Specifics that are computed from other attribute values. This means that the AttributeSet object in the response may not always be identical to the AttributeSet that the seller submitted. For example, suppose a category's Item Specifics include separate attributes for City (e.g., "San Jose"), State (e.g., "CA), and Zip Code (e.g., "95125"). In some categories, the GetItem response might contain those attributes plus an additional attribute that shows all three values together in one field (e.g., "San Jose, CA 95125") for display purposes.

When a listing includes product details and the seller has chosen to include additional stock summary information in the listing, the Description field is optional. This means items returned by GetItem (and other item-retrieval calls) are not guaranteed to contain a value in the Description field.

The Item Specifics data in the GetItem response includes attribute and value IDs, and literal values for the specified IDs. If your application has saved the attribute meta-data returned from GetAttributesCS that was in effect at the time of the listing start date, you can use the meta-data to determine the display name for each attribute.

Displaying Discount Pricing Information to Buyers

The Strikethrough Pricing and Minimum Advertised Price display treatments are available to only those sellers who have qualified to participate in the Discount Pricing program. If you are interested in becoming a member of this program, please contact your account manager or your Customer Service representative.

Some eBay fixed-price listings have discount pricing information, which specifies the original retail price of the item along with additional information about the visual treatment for the seller's discount price. The following sections describe the following two visual treatments of price information and their proper use:

For listings with Minimum Advertised Price details and a seller-specified price below the minimum advertised price, you are legally required to follow the rules for displaying the price of the item to potential buyers. You are bound by the terms of the API License Agreement to follow these rules. Refer to the API License Agreement for consequences of non-compliance.

Because of the legal implications of the Minimum Advertised Price treatment, applications that show item prices to buyers must first check items for discount price information (e.g., Item.DiscountPriceInfo) and the specific price treatment (e.g., Item.DiscountPriceInfo.PricingTreatment) to determine whether a special display treatment is needed for the item price. Discount price information is returned by the Finding API search calls, GetSingleItem and GetMultipleItems in the Shopping API, and GetItem in the Trading API.

Rules and guidelines for the display of discount pricing information apply to both active and completed items.

There are no specific pricing display rules associated with promotional sales as specified by Markdown Manager or the related API calls (e.g., SetPromotionalSale). If either Strikethrough Pricing or Minimum Advertised Price is specified for a listing, it supersedes any promotional sale treatment.

Display Guidelines for Strikethrough Pricing

Strikethrough Pricing is available on the eBay US, eBay UK, eBay Germany, eBay Canada (English and French), eBay France, eBay Italy, eBay Spain sites. Each of these sites have different display treatments for items that are listed with DiscountPriceInfo elements.

Strike Through Pricing is a visual treatment, consisting of an "original" price in a strikethrough font, as well as the current discounted item price in a non-strikethrough font. The original price is the price (excluding shipping and handling fees) at which the same item, or one that is virtually identical to it, is being offered for sale. On the UK and Germany (DE) sites, the seller can also specify that they have offered a similar item for sale on or off of eBay.

Note: The sites that support this feature all use different notations and phrasing for their strike-through pricing display treatments. For example, The US site makes use of the phrase "Compare at", while the UK site uses "RRP", and the DE site uses "UVP".

Determining Applicability

The display rules for Strikethrough Pricing apply when an item is listed with discount pricing information that results in PricingTreatment to return STP. To qualify for an STP display treatment, the item StartPrice price must be below the OriginalRetailPrice, as shown in the following snippet from an XML response from the Trading API:

API response sample for Strikethrough Pricing

...
<StartPrice currencyID="USD">149.99</CurrentPrice>
...
<DiscountPriceInfo>
   <OriginalRetailPrice currencyID="USD">159.99</OriginalRetailPrice>
   <PricingTreatment>STP</PricingTreatment>
   <SoldOneBay>true</SoldOneBay>
</DiscountPriceInfo>
...

The response XML for discount pricing information may vary slightly from API to API.

Treatment Rules

You are not required to use the Strikethrough Pricing treatment for listings that have strikethrough pricing information. You can simply display the item price without any special treatment.

If you choose to provide a Strikethrough Pricing treatment, the application should display the "original" price (Item.DiscountPriceInfo.OriginalRetailPrice) in a strikethrough price along with the BIN item price (Item.StartPrice) in a non-strikethrough font, and text to indicate there is a discount (for example, "Compare at"). The eBay UK and eBay Germany (DE) sites have slightly different discount display treatments, as described in the sections below.

If the item is listed on the UK or German (DE) sites, item can also include a SoldOneBay or SoldOffeBay field that, if used, indicates that the same seller offered a similar item for sale within the last 60 days at a price indicated by the OriginalRetailPrice value.

The following image provides an example of the Strikethrough Pricing visual treatment on the US site. eBay includes a footnote, indicated by the asterisk, to explain that the "Compare at" price comes from another online retailer, not eBay.

Strikethrough Pricing Example

When applying a Strikethrough Pricing treatment for an eBay listing, your application should display or include a link that displays explanatory text on pages upon which item price is hidden. The explanatory text in the US should read as follows:

A "Compare at" price is the price (excluding shipping and handling fees) this seller has provided at which the same item, or one that is virtually identical to it, is being offered for sale or has been offered for sale within the last 90 days.

Modify this text, as needed, for discounted items listed in the UK or Germany (DE).

Strikethrough Display Treatments on the UK Site

The eBay UK site employs the following strikethrough treatment styles:

Strikethrough Display Treatments on the Germany (DE) Site

The eBay Germany (DE) site employs the following strikethrough treatment styles:

Display Rules for Minimum Advertised Price

Minimum Advertised Price is supported on the eBay US site only.

While sellers have the freedom to set item prices as they see fit, some manufacturers restrict how prices on certain items can be displayed or communicated to others. When a listing includes Minimum Advertised Price (MAP) discount pricing information, there are legal requirements for the display of the item price to buyers when it is below the minimum advertised price set by the manufacturer. If a seller prices an item below the minimum advertised price, applications cannot display the price on any page until the buyer takes further action (such as clicking a button or link).

If the item price is greater than or equal to the minimum advertised price, no special treatment is needed to display the price.

Determining Applicability

The display rules for Minimum Advertised Price apply when an item is listed with discount pricing information that results in PricingTreatment to return MAP. To qualify for a MAP display treatment, the item StartPrice price must be below the MinimumAdvertisedPrice, as shown in the following snippet from an XML response from the Trading API:

API response sample for Minimum Advertised Price:

...
<StartPrice currencyID="USD">149.99</CurrentPrice>
...
<DiscountPriceInfo>
   <OriginalRetailPrice currencyID="USD">159.99</OriginalRetailPrice>
   <MinimumAdvertisedPrice currencyID="USD">154.99</MinimumAdvertisedPrice>
   <MinimumAdvertisedPriceExposure>DuringCheckout</MinimumAdvertisedPriceExposure>
   <PricingTreatment>MAP</PricingTreatment>
</DiscountPriceInfo>
...

The response XML for discount pricing information may vary slightly from API to API.

Treatment Rules

When the display rules for Minimum Advertised Price apply, the application cannot display the seller's lower price until the buyer takes further action. If the exposure setting (Item.DiscountPriceInfo.MinimumAdvertisedPriceExposure) is PreCheckout, the buyer can click a link or button to view the item's price in a pop-up window or subsequent page. If the exposure setting returns DuringCheckout, the price is displayed on eBay's Review and Confirm page in the checkout flow, or a comparable page in a third-party application that supports checkout capabilities, such as PlaceOffer. If your application sends buyers to eBay for checkout, your application should not display the item price to buyers when the exposure setting is DuringCheckout.

The following image shows a permissible visual treatment when item price is below the specified minimum advertised price. Users must click the "See Price Details" link to view the item price.

Minimum Advertised Price Treatment

When applying a Minimum Advertised Price treatment for an eBay listing, your application must display or include a link to display the following explanatory text on pages upon which item price is hidden:

Sellers have the right to set their own prices independently, but some manufacturers place restrictions on how those prices may be displayed or communicated to others. Because the seller's price on this item is below the manufacturer's "minimum advertised price" the manufacturer may not allow the seller to show you the seller's lower price until you take further action, such as clicking on a drop-down menu, placing the item in your cart, or proceeding to checkout. The steps required depend on the terms of the manufacturer's minimum advertised price policy. Taking these steps allows eBay to show you the seller's great price consistent with eBay's goal of always bringing consumers like you the lowest possible prices on the widest selection of products.

You should know that by taking these steps, you won't be required to purchase the product. You can always simply remove the item from your cart or not proceed with checkout if you decide not to buy the item.

These display rules for discount pricing apply to both active and completed items.

Additional Discount Pricing Information

For more information about discount pricing, see the following resources: