Trading API
 

XML Flow Tutorial: Completing a Sale

This tutorial consists of series of eBay API calls that describe a scenario for completing the sale of an auction item that has a winning bid. 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 end an item, communicate with the buyer, and set status for payment and shipping. This tutorial includes API calls made on behalf of a buyer, which are not typically incorporated into a selling application. Buyers communicate with sellers and leave feedback through the eBay site, normally. However, these calls perform tasks which may be useful for automating testing, as they emulate buyer interaction that may be handled by a selling application.

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

Related Tutorials:

Listing an Item, in which a seller gathers eBay category information (and other metadata) and lists an item.

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

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 Testing in the Sandbox in the Features Guide 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

Completing the Sale

The calls in this series illustrate how to sell an item to a high bidder, communicate with a buyer, and complete the sales transaction. The scenario ends with the buyer leaving Detailed Seller Rating (DSR) feedback for the seller.

Note: The steps in this tutorial are intended to illustrate concepts and/or help you with test cases. The steps do not not necessarily represent recommended best practices or the most common actions a buyer or seller would perform.

  1. With a solid bid on the item, Magical Bookseller decides to end the auction early by selling the item to the highest bidder.

    EndItem: end an auction early, selling to the current highest bidder

    Ending an auction early is not a typical action for most sellers. For testing purposes, though, it can be useful to terminate an auction early rather than wait for its natural end.

  2. When Bountiful Buyer receives notice that she has won the auction, she wants to ask the seller a question before she pays. She sends her question to Magical Bookseller through eBay's My Messages system.

    AddMemberMessageAAQToPartner: send a message to a transaction partner

    Note that AddMemberMessageAAQToPartner can only send messages between two transaction partners — two eBay members who are involved in a sale, such as a buyer or bidder and a seller. The Trading API does not provide a means of sending a message to another user outside a transactional relationship.

  3. Magical Bookseller, having listed many items on eBay, knows that it's a good idea to check periodically for open questions on the items she is selling. She retrieves unanswered messages for the Harry Potter book with a call to GetMemberMessages.

    GetMemberMessages: retrieve member messages for a specific item

    Note that this example uses a simplified form of the GetMemberMessages call for the sake of clarity. It gets all unanswered messages associated with a particular item ID — the item ID of Magical Bookseller's Harry Potter book. A real seller would probably use a more complex form of the call which retrieves unanswered messages created for any item ID within a specified time period.

  4. After reading Bountiful Buyer's message, Magical Bookseller sends a reply.

    AddMemberMessagesRTQ: respond to a question from an eBay member

  5. Bountiful Buyer is happy with Magical Bookseller's response, and proceeds to pay.

  6. To review the final details of the transaction, Magical Bookseller calls GetItemTransactions. From the response, she can gather information needed to complete the sale, including payment status, the FinalValueFee assessments, and the transaction ID. In addition, she can retrieve shipping addresses for the item.

    GetItemTransactions: retrieve information an item that was sold

    In this case, Magical Bookseller is using GetItemTransactions to get information on items she has sold. Note that a buyer could also use GetItemTransactions to get information on items she has bought.

    For sellers that have a high volume of sales, it would be more practical to use GetSellerTransactions with a date range to retrieve transaction information.

  7. Magical Bookseller sees that she has received payment from Bountiful Buyer. She packages and ships the book.

    After shipping the book, Magical Bookseller posts the shipping and tracking details so that the buyer can see them. In addition, because of the smooth transaction, she leaves positive feedback and detailed seller ratings for the buyer.

    CompleteSale: set paid status and shipping details for the item and leave feedback for buyer

  8. Bountiful Buyer receives the Harry Potter book a few days later. She is delighted by the book and its condition, so she leaves positive feedback for Magical Bookseller.

    LeaveFeedback: leave feedback for a transaction partner

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: