Trading API
 

XML Flow Tutorial: Listing an Item

This tutorial consists of series of eBay API calls that describe a scenario for listing an auction item on eBay. This scenario helps illustrate the purpose of API calls and their constraints and dependencies when used together. Each step in the scenario gives a link to an XML call sample in the Trading API Reference. The samples show how to perform that step using the API.

In this scenario, a fictitious eBay seller, Magical Bookseller, makes API calls to determine the correct category in which to list her item, a copy of Harry Potter and the Philosopher's Stone. Next, she makes API calls to determine the relevant features supported by the category she is considering. The scenario then goes through the common API steps to list an item.

This tutorial is the first in a series of tutorials for listing an item, buying the item, and completing the sale.

Related Tutorials:

Buying an Item, in which a buyer retrieves information about the seller of an item she is interested in and bids on the item.

Completing a Sale, in which the seller ends an item, communicates with the buyer, and completes the sale.

What's in this Tutorial

This tutorial contains the following sections:

Back to top

Complete Source Code

The API Flow tutorials use raw XML requests and responses. The XML call samples described in this tutorial can all be found in the Trading API Reference. Each step in the tutorial links to a corresponding XML call sample.

Back to top

Before You Begin

All the calls in the tutorial are performed in the Sandbox environment, using a seller test user. To make the calls in the tutorial, you must create your own Sandbox test user with a Sandbox authentication token. See Sandbox for more information.

The tutorial has no specific code requirements. You can run the XML samples in the API Test Tool on the eBay Developers Program website (you must log in).

Back to top

Step 1: Gathering eBay Category Information and Other Metadata

The first step when listing an item is to decide on the best category for listing the item. The seller wants to be sure that the item appears in searches performed by buyers looking for similar items. The Trading API provides several calls that return category information, with GetCategories being the best call for browsing categories and getting details on the eBay category tree.

  1. Magical Bookseller begins the listing process by using GetCategories to get a list of top-level categories on eBay's United States site.

    GetCategories: retrieve top-level categories for a site

    GetCategories returns a part of a specified parent category and all of its child categories down to a specified level of detail. In this case the call starts at the top of the tree (because it does not specify a parent category) and ends at level 1, that is, with the site's top-level categories.

  2. Reviewing the top-level category information, Magical Bookseller sees that the “Books” category is the most suitable one for the book she is selling, and that its category number is 267. She calls GetCategories again to get more details on this part of the category tree.

    GetCategories: retrieve details for a specific category

    In this case Magical Bookseller retrieves the part of the category tree that begins at category 267 (“Books”) and ends at category level 2. Because category 267 is at level 1, this call returns one additional level of detail from the category tree. That is, it returns category 267 and its immediate children.

    Looking at this additional detail, Magical Bookseller decides that “Fiction & Literature” (category 377) is the best category in which to list her Harry Potter book.

  3. Having chosen a listing category, Magical Bookseller can get information on the feature settings of that category.

    GetCategoryFeatures: get category settings for specific features

    Of particular interest to Magical Bookseller are the settings for ConditionValues, ListingType, PaymentMethod, ReturnPolicyEnabled, and ListingDuration. Magical Bookseller checks these features specifically, because the AddItem documentation indicates they are required for some categories.

    Magical Bookseller sees that for the category she has chosen, ReturnPolicyEnabled is set to true, which means it is required for that category.

  4. Magical Bookseller needs to know more about the return policy options on the United States site, so she retrieves that information from the site's metadata.

    GeteBayDetails: retrieve return-policy options for the site

    Magical Bookseller's call to GeteBayDetails specifies the type of metadata she wants, in this case “ReturnPolicyDetails.”

    Note that the metadata for eBay sites does not often change. It is typical for API users to refresh their site metadata once a day, and store the data for later use in their API calls.

Back to top

Step 2: Listing the Item

Once Magical Bookseller has collected the information she needs about the category and eBay features, such as Return Policy options, she is ready to list her book.

  1. Magical Bookseller wants to display a picture with her book listing, and she wants to use eBay Picture Services (EPS) to host it. She uploads the picture to EPS.

    UploadSiteHostedPictures: upload an image to eBay Picture Services

  2. Magical Bookseller prepares a listing for her item. To ensure that her listing contains no errors, she verifies it before listing it for sale.

    VerifyAddItem: test an item listing for validity

    VerifyAddItem also displays the fees that will be incurred if the item is listing it for sale. It is a good tool for checking a listing for correctness (and cost) without paying insertion fees.

  3. The response from VerifyAddItem indicates that the listing is valid, and Magical Bookseller considers the listing fees acceptable. She is now ready to list the item.

    AddItem: list an item for auction on eBay

    Note: Sandbox listing fees do not match Production listing fees, so they should not be used to estimate actual fees. Fees returned from VerifyAddItem and AddItem do not include the transaction fees; these fees cannot be calculated until the item is sold. Additional fees can also be incurred if the listing is revised.

  4. Magical Bookseller retrieves the item listing she just submitted to the site to ensure that it includes all the settings she expected.

    GetItem: retrieve a listing's item details

    The response from this call shows all of the listing's details, including listing duration, category, type of item, payment methods allowed, auction start and end times, current price (which will be the starting price for a fresh listing), and more.

    Note: Calling GetItem for every listed item is not a recommended best practice and should not be part of a standard application flow. GetItem is useful when you are developing or debugging your application.

  5. After reviewing the listing's item details and seeing the item listing on the eBay site, Magical Bookseller wants to modify some of the item properties. Specifically, she wants to add a subtitle to the listing and change a few things in the item description.

    ReviseItem: add a subtitle and modify the item description

    Note: ReviseItem does not give a seller complete freedom to change item listings. For example, it can change certain listing properties only if there are no bids on the item, and the listing has at least 12 more hours to run. Thus it is good practice to avoid using ReviseItem by checking one's listings carefully before submitting them. Item listings sometimes have to be revised, though, so ReviseItem is an important feature in most listing applications.

    To verify the changes, use GetItem and include the ItemID and DetailLevel set to ItemReturnDescription.

Back to top

Notes and Next Steps

This section contains notes about the tutorial and suggestions for extending it.

What's Next

Here are some suggestions for ways you could modify or extend the tutorial to learn more about the API:

Additional Resources

More information about the Trading API is available at these locations: