Basic Building Blocks

This chapter describes some basic objects and concepts of the Trading API..

Subtopics

Items and Listings

Categories

Choosing a Listing Option

Users

Order Line Items

Feedback

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:

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 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:

Creating Item Listings

Retrieving Items

Managing Inventory

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.

Categories

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 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:

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
 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 with Item Specifics
 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:

Users

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

Feedback

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.