Basic Building Blocks
This chapter describes the basic concepts of eBay APIs.
Items and Listings
Choosing a Listing Option
Order Line Items
Items and Listings
An item is something sellable or marketable on eBay. A listing is an entry on eBay that offers or advertises one or more items for sale. eBay members (and this documentation) sometimes use the terms "item" and "listing" interchangeably. Technically, a listing is the advertisement of what you're selling, whereas the items are the objects that are being advertised within the listing. A listing can contain one or more items. Items can be listed for competitive bidding (as auctions), without bidding (fixed-price), or as classified ads.
The same defining values a seller would supply when listing the item through an eBay web site are supplied in the Item object. Programmatically supplying item data also lends itself to the creation of applications that have no user interface at all, such as an application that automatically lists items to the eBay site from an inventory database, all without direct human intervention.
The data a seller (or an application) supplies to define an item and its listing includes such things as:
- The title under which the item appears on the eBay site
- The price at which the seller wishes to sell the item
- The length of time (or duration) the item's listing appears on the eBay site
- The category in which the item can be found by buyers
- Specifications from which the costs of shipping can be calculated
- The methods by which the seller enables the buyer to pay for the item
- Where (geographical regions) the seller is willing to ship the item
The Item object is reusable. When used with operations such as AddItem, the data in the Item object is passed to eBay where it is used to list or relist the item. When used with such operations as GetSellerList and GetItem, the Item object is populated with the listing data retrieved from eBay.
For technical how-to information related to listing, retrieving, and managing items, see the following:
Creating Item Listings
Listing Types (Formats)
eBay offers several listing types to accommodate the selling needs, styles, and approaches of different sellers. The list below describes the listing types available.
Not all listing types can be created with AddItem and related calls, and some listing types may be available on some sites but not in the API. Some listing types have prerequisites the seller must meet before using them (such as a minimum aggregate Feedback score).
The listing types differ in how a sale is made (progressive bidding or immediate purchase). Other differences include the number of items that can be offered for sale in a listing, the number of days a listing may be active, and how and when the listing ends.
The eBay listing types are summarized below. For more information on using each listing type, see the Selecting a selling format
- Auction listings: for the duration of the listing, the seller receives bids for the item. The highest bidder (who also meets the Reserve Price, if set up) at the end of the listing wins the item. The seller also has the option of implementing the Buy It Now feature on the item, which allows buyers to buy the item at the "Buy It Now" price. However, the Buy It Now feature is disabled for the listing as soon as it receives the first bid that meets or exceeds the Reserve Price, if set up. Note: Historically, the Best Offer feature has not been available for auction listings, but beginning with Version 1027, scheduled to roll out the first week in August 2017, sellers in the US, UK, and DE sites will be able to offer the Best Offer feature in auction listings. Once this new capability rolls out, the seller can offer Buy It Now or Best Offer in an auction listing, but not both.
- Fixed-price listing: the seller lists an item at a fixed-price and buyers are able to purchase the item without bidding. The seller has the option of implementing the Best Offer feature on a fixed-price listing, where the buyer can propose a "Best Offer" that has a price which is lower than the fixed-price for the item. It is up to the seller to accept or reject any Best Offer that is received for the item. The seller selects a listing duration that is supported for the corresponding eBay site, or that seller can select the "Good 'Til Cancelled" option. Good 'Til Cancelled listings will automatically renew every 30 days as long as their is inventory remaining for the listing. A fixed-price listing automatically ends when the inventory of the item is at 0. Fixed-price listings typically end when all inventory is sold, but sellers can select the "Out-of-Stock" option in My eBay Site Preferences, and listings with 0 quantity will be kept alive by eBay (but hidden from search results), and then the seller can add more inventory to the listing.
- Classified Ads: with this listing type, the seller is announcing the availability of his/her item on eBay, but if a transaction (buyer purchases item from the seller) occurs, it is done off of eBay's platform.
- Motors National listings: this is a motor vehicle listing, and the vehicle is available for purchase for anyone in the country. It is up to the seller to use an auction listing, a fixed-price listing, or accept Best Offers.
- Motors Local Market listing (for dealership subscribers only): this listing type is good for late model, everyday, or unique vehicles that would interest local rather than national buyers. It requires that the seller have a Local Market subscription.
A category is a named grouping of similar items on eBay, such as "Collectibles", "Fashion", or "Electronics". From the perspective of a user, categories are organized into a hierarchical structure (conceptually similar to the directories in a file system). In the following example, Collectibles is the root category.
Collectibles > Autographs > Political > Presidential
It is important that an item be in the proper category. Buyers benefit from categories in that they can go to a specific category to find something they wish to buy (or to simply browse the available items and "impulse shop"), because they know that the category contains only the type of items they are interested in and the category is the designated place to find them. Sellers can list items in a secondary category in most instances, except some categories prohibit this. Additional fees may apply when listing items in two categories. For more information about listing items in two categories, see the Listing in 2 categories help topic.
Categories vary from one eBay site to the next. That is, the US eBay site has different categories than, say, the Germany eBay site. Many of the categories serve the same purpose on all sites (though they are named in the language of the site), but a site also contains categories that are only of regional interest or of interest to a particular culture.
The using the Trading API GetCategories call you can download all the categories for a specific site. Categories are updated about once a month. An application should download the categories once and then refresh it once a day. For more information see, Applying Categories.
For more information about how sellers select appropriate categories, see the Selecting a category help topic. For more information about how buyers look for items, see the Finding items help topic. For information about working with categories, see Maintaining Category Data.
Choosing a Listing Option
In addition to defining the basic properties of an item, some categories support options that let you fill in item descriptions more quickly by using stock product information from an eBay catalog.
The options that are available depend on the item's category:
- Listing the standard way
With this option, you enter all the descriptive information about the item yourself. This option is available in all categories.
- Listing with eBay Catalog product details
With this option, you identify an available eBay Catalog product that is similar to your item, and then eBay uses that catalog product's details to prefill some of your listing's details, including product title, product description, product aspects, and links to product stock photo(s). and to add other information to supplement your listing description. This option is available in certain categories (which you can determine based on an API call, as described later in this document).
Beginning in May 2018, some eBay categories will start requiring that listings be associated with eBay Catalog products in order for those listings to appear in eBay's Product-Based Shopping Experience. See the Product-Based Shopping Experience landing page for more information.
Listing with Product Details
To include eBay Catalog product details in a listing, you pass in an eBay Product ID (EPID), which is a unique identifier of the catalog product.
If you don't know the EPID for a catalog product, you can also use an industry-standard product identifier, but it is possible that eBay will not be able to find the best catalog product match without an EPID. Common product identifiers are discussed below:
- A Universal Product Code (UPC)
- The product's brand and manufacturer part number
- An International Standard Book Number (ISBN) for items like books, DVDs, music CDs, and video games
- A European Article Number (EAN) (similar to an ISBN, in Europe)
- For event-based listings, the event name, venue, and date.
eBay then attempts to match that identifier to a product in the catalog to determine the EPID for you, and adds the catalog product details to your listing.
About Listing with Product Details on the eBay Web Site
As described earlier in this chapter, items in certain categories can have item specifics whose values are well known and don't vary from listing to listing. For example, in the Movies category, buyers would expect a popular movie's title, rating, and film credits to be the same no matter who the seller is. Instead of filling in this standard information for every listing, a seller can create a listing in which this information has already been partially filled out (pre-filled). This data is called product details.
You can use key attributes such as ISBN, UPC, or Manufacturer Part Number (depending on the product type), as well as keywords like Title to pull up stock listing information on items in categories that support this feature. You can then select content, including stock photos, descriptions, and supplemental information (like song lists, film descriptions, etc.) that will be added to a listing automatically. At the time of this writing, Media categories (Books, DVDs & Movies, Music, and Video Games) and Consumer Electronics categories (Digital Cameras, Cell Phones, and PDAs) support product details.
For some categories, the use of product details is optional. However, some categories require that a product ID be supplied at listing time. For more information about required product identifiers, see Build your business page in eBay's Seller Center. Sellers can use the GetCategoryFeatures call in the Trading API to see which categories support or require product identifiers when listing items in that category. Or, the seller can look at the Structured Data - Product Identifiers help page.
Buyers and sellers can use product information to list and find similar items more precisely and to ascertain the details of items more easily when viewing items. By using product details, sellers worldwide can describe their items more fully in fewer steps and in a way that makes their listings easier to find.
Product details do not replace a seller's own item description; it just adds more information to the listing. Sellers still assume full responsibility for the content of the listing and the item offered.
View Item page: Once the item has been listed, the product details are included on the View Item page along with the seller's usual title and description.
The figure below shows a View Item page for a book listing that includes stock product information. In this case, the user used the stock photo instead of providing their own picture, and they specified that they wanted to include more stock information in their listing in addition to the pre-filled Item Specifics.
Figure: View Item Page for a Listing with Product Details
Listing with Item Specifics
As the seller fills in their listing description, they can increase the likelihood of buyers finding the item by including common search terms in the description. In many categories, there are well-known, category-specific aspects of items that buyers want to search on. For example, in book categories, buyers typically want to search by subject or author. In event ticket categories, buyers may want to search by particular event types (e.g., concerts).
To make it easier for sellers to determine these category-specific search keywords (like "Subject") and include them in their listings, eBay provides a special section in the item description called Item Specifics. Item Specifics are well-known, predefined characteristics that are common to all items in a particular category. For example, if you are listing in the Fiction & Nonfiction Books category, "Subject" and "Publication Year" are some Item Specifics for a book.
When you list the standard way, many categories provide Item Specifics that you can fill in. In most cases, filling them in is optional. In a few categories, Item Specifics are required. Recommended and required Item Specifics for categories can be obtained by using the GetCategorySpecifics call in the Trading API.
When you list with product details, Item Specifics common to the listing category are always included in the listing.
The figure below shows an example of Item Specifics that a seller has filled in while listing an item on an eBay Web site.
Figure: Listing the Standard Way with Item Specifics
If you are new to the API and you are developing and testing your first listing application, you might start by implementing support for listing the standard way with a basic description. Then, after you have created a few different kinds of listings successfully, add support for listing with Item Specifics and product details.
Typically, end-user applications that support Item Specifics need to implement one or more of these capabilities:
- When a seller is listing an item in an Item Specifics-enabled category, display the available Item Specifics for that category.
- When a user is searching for items, display the available aspects for the selected category.
- When a seller is ready to add, revise, relist, or verify the addition of an item, pass the selected Item Specifics and values to eBay.
- When displaying a listed item to a user, display the Item Specifics that have been set on the item.
About Item Specifics on the eBay Web Site
Within certain categories, there may be additional, category-specific aspects of items that buyers want to search on. For example, in book categories, buyers may want to search by format (e.g., softcover) or publication year. In event ticket categories, buyers may want to search for particular event types (e.g., concerts) or venues.
To make it easier for sellers to predict the category-specific search keywords (like "Softcover") that buyers will use and include them in their listings, eBay provides a special Item Specifics section in the item description. The Item Specifics section contains a set of well-known, predefined fields that are common to all items in a particular category. For example, if you are listing in the Fiction & Nonfiction category, Format and Publication Year are some Item Specifics for a book. If you are listing in the Event Tickets category, Event and Venue would be some Item Specifics for a ticket.
Many categories support Item Specifics, and this feature is being added to more categories on a regular basis.
Figure: Item Specifics in the eBay User Interface
By using Item Specifics, sellers worldwide can describe their items using standardized search keywords. Buyers and sellers can use Item Specifics to find items more easily when searching eBay. For example, in the browsing flow, buyers use product finders to filter listings according to Item Specifics. Item Specifics also help buyers ascertain the details of items more easily when viewing items. See the eBay online help for more information about how buyers and sellers use Item Specifics on eBay.
Item Specifics Online Help:
In the Sell Your Item flow, the way you enter Item Specifics varies depending on the listing option you choose:
- When you list the standard way, many categories support Item Specifics, but filling them in is usually optional. A few categories (such as Real Estate in some countries) require you to fill in certain Item Specifics in order to list the item. Some categories do not support Item Specifics at all. In any case, you also need to provide your own free-form description of the item.
When you list the standard way with Item Specifics, you fill in the values of the Item Specifics yourself (i.e., eBay does not fill them in for you). For example, if you are listing a book, you fill in the Subject field by choosing from a list of subjects, and you fill in the Publication Year field by entering a value. In some cases, the value you select for one field will control the availability of other fields or the choice of values for certain fields. For example, for a Tickets listing, the state or province you choose controls the list of names that will appear in the City field.
For listing with item specifics, see Working with Custom Item Specifics.
- When you list with product details, Item Specifics are always available. The difference is that eBay fills in many of the Item Specifics for you based on stock product information that you choose from an eBay catalog.
To search with catalog product details, see FindProducts in the Shopping API.
For some products, some Item Specifics might not be pre-filled, so you can fill them in yourself or select them from a list. For example, if you are listing a book, you can fill in a Condition field by selecting "New" or "Used."
Figure: Standard Item Specifics vs. Pre-filled Item Specifics
In the context of eBay APIs, a user is someone who has registered as a member of eBay. Anyone can browse the eBay site without registering as a user; however, eBay APIs functionality supports only registered users. Users are often referred to by their roles as bidder, buyer, seller, store owner or application developer.
An eBay user has a unique identifier by which the user can be referred. This user ID is unique across all of the eBay sites, US and global.
In the API, a user is represented by the User object. This object contains general information about a user, such as the user ID, whether the user is a new eBay member, and the eBay site on which the user registered. It also contains information that plays a part in buying or selling an item, like the user's aggregate Feedback score, an indication of whether the user is an eBay Store owner (and the Store's location), and an indication of whether the user is a Power Seller. The data for a user can be retrieved using GetUser, which populates a User object with the data it retrieves from eBay.
For more information on retrieving information about a user from eBay, see Retrieving User Information.
See also eBay User Roles.
Order Line Items (Transactions) and Checkout
An order line item (a line item within an order) is the record of one buyer's commitment to purchase one or more identical items from the same listing. In the API, this is also sometimes called a transaction for historical reasons. Many API elements still use that term — the Transaction API object contains the information for one order line item.
Order line items are created when one of the following occurs:
- A buyer wins an auction.
- A buyer uses Buy It Now to commit to purchasing an auction item at the Buy It Now price before any bids are placed.
- A buyer commits to purchase a quantity of 1 or more of an identical item from a fixed-price listing.
A single order line item can contain multiple quantity of an identical item purchased at the same time in the same listing. In a multi-variation listing, the items must be the same variation. When a buyer increases the quantity of a selected item in the shopping cart, a single order line item will be created when the buyer commits to the purchase. However, if a buyer selects an item from a listing, commits to purchase it, then returns to the same listing and selects the identical item to add to the order, the two items will be considered separate order line items.
If a seller offers multiple quantity of a specific item within a fixed-price listing, and multiple buyers purchase those items, that listing will spawn multiple order line items (one from each buyer).
If a buyer purchases items from different listings by the same seller before paying for them, the seller can group the purchases into the same order (which can form the basis for an invoice), where each purchase is reflected by an order line item within that order.
Auction listings result in only one order line item, and this occurs either at the end of the listing with a winning bidder, or when the buyer uses the Buy It Now option.
Checkout encompasses the period of time between creation of the order line item and the shipping of the item. During the checkout flow, interactions between the seller and the buyer affect data values for the corresponding order line item. For instance, the CheckoutStatus container in order and order line item retrieval calls has fields that indicate the current status of the order line item (checkout is complete (paid for) or incomplete (not paid). The base amount of the order line item is shown in the Transaction.TransactionPrice field and the shipping and handling costs are shown in the Transaction.ActualShippingCost and Transaction.ActualHandlingCost fields. If PayPal is the selected payment method for the item, then PayPal would set the Transaction.TransactionPrice field at the end of the checkout process.
An order line item is represented by the Transaction object. To retrieve order line item data for a particular listing, you use GetItemTransactions. This call can result in the return of zero or multiple order line items. To retrieve all single and multiple (Combined Invoice) order line items for a seller's account, you use GetOrders.
For technical how-to information related to order retrieval calls, see Completing the Sale.
eBay provides a Feedback system that allows buyer and seller partners to leave feedback concerning their mutual transaction. about the other participant. The Feedback score for a user is a cumulative quantitative expression of the desirability of dealing with a particular eBay user as a buyer or a seller. A user's Feedback score (and their Positive feedback percentage) essentially provides an overview of the user's reputation on the eBay site.
Buyers can leave a positive, negative, or neutral rating and a short comment for sellers. Sellers can only leave a positive rating and a short comment for buyers, or they can choose not to leave feedback. A given user's feedback score is a calculation based on the positive, neutral, and negative ratings. A seller gets +1 point for a positive rating, -1 point for a negative rating, and no points for a neutral rating. For more information, see the Feedback scores, stars, and your reputation help topic. A seller's Feedback score appears on the pages for items listed by that seller. A buyer's Feedback score appears with bids that buyer places on items. The eBay site provides a page where any one registered user may view the Feedback score and history for any other eBay user, unless the user sets their profile to private (see Making your Feedback Profile public (or private) for more information). In API and SDK applications, a user can leave Feedback for another user or retrieve Feedback of another user.
In addition to the standard Feedback that a buyer can leave for a seller, the buyer can also choose to leave detailed seller ratings for various aspects of the transaction, such as accurate item description, communication from the seller, shipping time, and handling charges. For more information, see the Detailed Seller Ratings help topic.
On the eBay site (but not through the API), members can mutually withdraw Feedback for an order if both parties involved in the order agree to do so. In this case, Feedback left by both parties is withdrawn at the same time. Withdrawn Feedback does not affect the Feedback score for either user, but the original comments remain.
In applications, leaving Feedback for another user is done with LeaveFeedback and retrieving feedback about another user is done with GetFeedback.
For technical how-to information related to Feedback (leaving and getting feedback) see Leaving and Getting Feedback.
Copyright © 2005–2016 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.