Basic Building Blocks
This chapter describes some basic objects and concepts of the Trading API..
Items and Listings
An item (or product) is something that a seller wants to sell on eBay. A listing is the entity on an eBay marketplace where that item is for sale. Although the terms item and listing may at times be used interchangeably, technically speaking, a listing is the advertisement of what you're selling, and includes price, promotional offers (if any), buying options, and shipping/pick-up options.
Below are the three types of listings on eBay:
- fixed-price (also called 'Buy it Now'): a fixed-price listing can contain multiple quantity of the same item, or can even have multiple quantity of multiple variations of an item. For example, a seller could be selling t-shirts in various size and color combinations in the same listing, and interested buyers select the size and color combination that they want. Except for just a few exceptions globally, the duration of all fixed-price listings are 'Good 'til Cancelled' (GTC), which means that the listing will remain active until all inventory is depleted and/or the seller chooses to end the listing.
- auctions: an auction listing involves competitive bidding from multiple eBay users on the same item. Unlike fixed-price listings, the quantity of an auction item can only be 1, and the listing duration may vary based on the listing category and on the seller's preference. With an auction listing, the seller can also set a Reserve Price, a price that must be met by the highest bidder by the end of the auction, or the sale will not occur.
- classified ads: with a classified ad, the seller is advertising an item on eBay, but the actual transaction (exchange of the item and money) happens off of eBay's platform. Only a limited number of eBay categories support classified ad listings, including Real Estate and motor vehicle categories. With classified ad listings, the seller is charged a higher, 'up-front' listing fee, but is not charged a 'Final Value Fee' because eBay has no way of knowing the final sale price negotiated between seller and buyer
The same defining values a seller would supply when listing the item through an eBay web site, mobile app, or listing tool, are supplied through the Item object when using a Trading API call to create or revise a listing. This Item object can be programmatically used to create an application that automatically lists items to the eBay site from an inventory database, all without direct human intervention.
Some of the basic data that a seller (or an application) supplies to define an item and its listing are highlighted below:
- The listing title under which the item appears in Search Results or on a View Item page
- The 'Buy it Now' price at which the seller wishes to sell the item, or the starting or current bid price of an auction item
- The duration of the listing, or how long it will be available for sale or bidding; the durations vary the most for auction listings, as all fixed-priced listings (except for a few motor vehicle categories) are 'GTC', and most classified ads run for either 30 or 90 days or until a sale happens.
- The eBay listing category (also known as a 'leaf category') in which the item is placed and found by prospective buyers.
- The available shipping service options and costs associated with each of those options.
- The available payment methods that can be used by the buyer to pay for the item. Note that sellers only have to specify payment methods for listings where the transactions between buyer and seller will happen off of eBay's platform.
- The ship-to locations where the seller is willing to ship the item. Some sellers only want to ship domestically, some sellers may be willing to ship worldwide, and some may want to customize the domestic and international locations where they are willing to ship to.
The data in the Item object is persistent and reusable. After an eBay listing is created with an AddItem or AddFixedPriceItem call, a lot of the same static data in the Item object will be returned when the GetItem or GetSellerList calls are used. Similarly, some of the same data in the Item object could be reused when revising a listing with a ReviseItem , ReviseFixedPriceItem, or ReviseInventoryStatus call, or relisting an item with an RelistItem or RelistFixedPriceItem call.
For more information on creating, retrieving, and managing listings, see the following topics:
Listing Types (Formats)
The types of listing formats offered by eBay was covered briefly earlier in this document, but this section will provide some more detail.
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 help page.
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.
The seller can offer Buy It Now or Best Offer in an auction listing, but not both, and once the first qualifying bid is received for the auction listing, either of these features is disabled.
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 or counteroffer that is received for the item.
The duration of all fixed-price listings must be set to "Good 'Til Cancelled". No other listing durations are supported. The only exceptions to this rule are motor-vehicle categories (6001, 6024, 6038, 26429, and 66466) on eBay Motors and on motor-vehicle categories (9800) on the eBay UK and eBay Italy sites.
"Good 'Til Cancelled" listings automatically renew each month, as long as there is inventory remaining for the listing. Generally, a fixed-price listing automatically ends when the available quantity of the item is at 0, 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.
With this listing type, the seller is announcing the availability of the item on eBay, but if a transaction (buyer purchases item from the seller) occurs, it is done off of eBay's platform. This listing type is not available for all eBay categories. A seller can use the GetCategoryFeatures call to see which categories support the Classified Ad format.
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 classified ad.
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 top-level (or 'L1') category on an eBay marketplace is a named grouping of similar items, such as "Collectibles", "Fashion", or "Electronics". Categories are organized into a hierarchical structure (conceptually similar to the directories in a file system). In the following example, Collectibles is the Level 1 (L1) category, and Presidential is the 'leaf' category, and a Level 4 (L4) category. All categories that contain actual listings are called leaf categories. Below is the full path to the category, and the full name of the leaf category, as it will be displayed on the eBay.com site, is actually 'Collectible Presidential Autographs'.
Collectibles > Autographs > Political > Presidential
It is important that a seller place an item in the proper category, as it should increase traffic to and sales from the listing. In eligible categories, sellers can list items in an additional, "secondary" category. However, additional fees may apply when listing items in two categories.
There are CategoryID values associated with every eBay category. The CategoryID value is generally what is used when using API calls to identify a category.
Categories and the category hierarchy will vary from one eBay marketplace to the next. For example, the category hierarchy and available categories on the US eBay site varies from the eBay Germany site. For categories that are basically the same, but on different marketplaces, the CategoryID value may be the same, but the category name may vary slightly, and the category name is always localized into the default language for the site. Each eBay marketplace will have unique categories that are only of regional interest, or of interest to a particular culture.
You can use the Trading API's GetCategories call to retrieve all categories for a specific eBay marketplace. This call can also be used to retrieve a subset of the category hierarchy. For example, a user may just want to grab all categories under the 'Collectibles' L1 category. Categories and/or the category hierarchy on an eBay marketplace are typically updated about once per quarter. An application could download the categories once and then periodically run the GetCategories call to check if the CategoryVersion and/or UpdateTime values has been updated. For more information see, Applying Categories.
For more information about how sellers select appropriate categories, see the Adding a category to your listing help topic. For more information about how buyers look for items, see the How to use search 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 prefill item details by referencing a product definition in the eBay catalog.
The options that are available depend on the item's category:
- Listing the standard way
- Listing with eBay Catalog product details
With this option, you enter all the descriptive information about the item and listing yourself. This option is available in all categories.
With this option, you reference an available eBay Catalog product using an eBay Product Identifier (also known as an 'ePID'), 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 stock photo(s). This option is available in categories where catalog products exist.
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 (MPN)
- An International Standard Book Number (ISBN) for items like books, DVDs, music CDs, and video games
- A European Article Number (EAN)
eBay then attempts to match that identifier to a product in the catalog, and will add the catalog product details to your listing if a match is found.
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 (prefilled). 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.
For all categories, the use of product details is optional, but it can be an optimal way to create listings. For more information about product identifiers, see the Listing with Structured Data Seller Center page. Sellers can use the GetCategoryFeatures call in the Trading API to see which categories support 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.
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 for listings called Item Specifics. Item Specifics are well-known, pre-defined 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. Many categories require at least a few Item Specifics. Other Item Specifics are either recommended or optional. Required, recommended, and optional Item Specifics for each category 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.
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.
In the context of eBay traditional 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 traditional 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 APIs, 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 seller accepts the buyer's Best Offer or counteroffer price.
A single order line item can contain multiple quantity of an identical item purchased at the same time in the same listing. In a multiple-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.
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 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.