Basic Building Blocks

This chapter describes the basic concepts of eBay APIs.

Topics:

Items and Listings

Categories

Choosing a Listing Option

Users

Order Line Items

Feedback

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

Retrieving Items

Managing Inventory

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

Categories

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 with Product Details

To include product details in a listing, you pass in an eBay Product ID (EPID), which is a unique reference number that eBay defines for all products in our catalogs.

If you don't already know the EPID (this is common the first time you list a particular type of item), you can use an industry-standard identifier, such as:

eBay then matches that identifier to a product in the catalog to determine the EPID for you, and adds the 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
View Item Page

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

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
Item Specifics in the 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:

http://pages.ebay.com/help/sell/item_specifics.html

In the Sell Your Item flow, the way you enter Item Specifics varies depending on the listing option you choose:

Users

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

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