Completing the Sale

This section discusses orders and how to work with them during the processing that occurs after a winning bidder is determined (for auction listings) or a purchase is made (for fixed-price listings). This section also discusses the major activities a seller is concerned with upon the completion of a sale. These activities are partially or wholly supported by applications. Some aspects of some of these activities cannot, or are not, performed with an application and instead must be done on the eBay site.

Applications retrieve whole lists of order line items for a particular seller using GetSellerTransactions. Retrieving the order line item data for a specific listing is done with GetItemTransactions. However, it is more efficient to use GetOrders to retrieve all single and multiple line item orders.

One reason an application returns a group of orders is to display the order line item data in a visual report. An end user can use this report to take various actions, such as contact some buyers to send them information.

Another reason for retrieving groups of orders is for processing the data outside the context of a user interface or human intervention. For example, an application could retrieve a list of the orders to assess activity, and only alert the seller if a predetermined condition exists (e.g., a buyer requests the total amount to pay, including shipping).

After an item is sold, the seller must ship that item to the buyer. The buyer and seller should leave each other feedback. Applications submit feedback with LeaveFeedback or CompleteSale. To retrieve feedback for a user, use GetFeedback.


Retrieving Order Line Item Data and Managing Orders

CompleteSale API Call

Shipping the Item

Final Value Fees and Credits

Leaving and Getting Feedback

Making Second Chance Offers for Items

Retrieving Order Line Item Data and Managing Orders

The Trading API offers four calls that let you retrieve order line item data directly. The four calls are summarized below:

In addition, an application can use an optional feature called Platform Notifications, wherein eBay pushes order line item data to a URL that the application monitors. See Subscribing to Platform Notifications for more information.

These calls can potentially return a very large number of order line items. You can use filters, such as NumberOfDays, to reduce the number of items returned.

Some order line items are processed with back-end batch jobs. This means there can be a short delay between an end time of an item and the recording of the initial order line item entry in the eBay database. Therefore, to make sure you do not miss any order line items, use the current date as the most recent date in the range to make sure you have captured all possible order line items and any updates. For each listing, use GetItemTransactions at set intervals to get updates on any order line items that are new or have changed status since the last time you executed GetItemTransactions for that listing.

Depending on the window of time you specify, the call can still return hundreds of order line items. Therefore, it is recommended that you configure the request to get one page of data at a time (where each page contains a more manageable number of order line items). Pagination breaks up the total data set into smaller chunks.

Retrieving Order Line Item Data Directly

GetOrders retrieves all orders in which the authenticated caller is involved as a buyer or seller. The retrieved orders can include single line item orders and multiple line item orders. Based on the buyer or seller's activity, the response can be quite large. This call has several filers you can use to restrict the number of orders returned. For information about these filters, see the GetOrders API Reference.

Alternatively, GetItemTransactions can be used to retrieve all order line items for a specific listing based on an ItemID. A caller should also use GetItemTransactions when the application's user needs to retrieve order line items for an item that was listed by someone else (another seller). GetOrders and GetSellerTransactions only retrieve data for the caller making the request.

Best Practice for GetOrders

To check the status of and process all orders on a continuous basis, make a call to GetOrders every 15 minutes. In the request, make sure:

Iterate through each order (OrderArray.Order) returned in the call. Checkout is complete and the order may be sent if the OrderArray.Order.CheckoutStatus.Status value is Complete, and the OrderArray.Order.CheckoutStatus.eBayPaymentStatus value is NoPaymentFailure. If any other values are returned in these fields, confirmation of buyer payment is not yet confirmed, and the item should not yet be shipped.

You can have eBay send order line item data to a URL that the application monitors. For more information see Working with Platform Notifications.

Retrieving the Order Line Items for a Single Item

To retrieve the order line item data for one specified fixed-price listing, use GetItemTransactions. In general, only use this call when you cannot use GetSellerTransactions. For more information, see GetItemTransactions API Reference.

Retrieving the Order Line Items for a Specific Seller

To retrieve the order line item data for a specified seller, you can use GetOrders, or alternatively, GetSellerTransactions. Using GetSellerTransactions involves three general steps: setting up the execution environment, specifying the order line items to return, and making the API call.

An eBay user cannot use GetSellerTransactions to retrieve another seller's list of order line item data. eBay uses the security credentials (see Security) to determine whose order line item data to return.

CompleteSale API Call

The CompleteSale call can be used by the seller to do the following tasks:

For more information, see CompleteSale.

Shipping the Item

After an item has been sold, the seller must send the item to the buyer. The costs for shipping the item (if not paid for by the seller) are included in the total price charged to the buyer for the item. For more information on calculating shipping costs, see Specifying Calculated Shipping.

During the checkout process, the buyer selects the shipping service from those specified by the seller. The shipping method the buyer selects is part of the data retrieved for the order line item, contained in its shipping details. The seller must then use that shipping method to send the item to the buyer.

The seller has the option of purchasing eBay shipping labels or they can pay for shipping outside of eBay's platform. Generally, the seller will get better shipping rates using eBay shipping labels, and the item will automatically get marked as shipped once the seller purchases the shipping label. The shipment tracking information will also be tied to the order and available for the buyer to see.

After the item has been paid for and shipped, the seller can use CompleteSale (see CompleteSale) to update the paid and shipped status in My eBay. If shipment tracking is used (see the preceding paragraph), you can modify or delete the shipment tracking details in CompleteSale as well. For details, see the Call Reference entry for CompleteSale.

Final Value Fees and Credits

For every sale, the seller is charged a Final Value Fee (FVF). This fee is in addition to any listing-related fees that were charged at listing time.

The Final Value Fee applies right when the buyer commits to purchasing the item. If the buyer requests that the order be cancelled, and the seller grants that request, the seller may be eligible to get a credit for the Final Value Fee. The seller may also get a Final Value Fee credit if the buyer never pays for the item and the seller wins an Unpaid Item case.

The calculation of the Final Value Fee depends on several things, such as site, type of item, etc. For information on how Final Value Fees are calculated, see the Final Value Fee eBay help page.

The output of AddItem includes fees the seller incurs for the listing. Those fees don't include the Final Value Fee, which cannot be calculated until the item is sold.

To retrieve Final Value Fees, pass IncludeFinalValueFee with a value of True in GetItemTransactions, GetSellerTransactions, GetOrders, or GetOrderTransactions. The Final Value Fee is returned in Transaction.FinalValueFee.

For non-store, North American auction listings, the FinalValueFee value may change upon checkout (payment). The initial Final Value Fee will be based on the Transaction price. The final Final Value Fee will be updated based on the additional shipping/handling/insurance costs.

Under certain circumstances, sellers may request a Final Value Fee credit. For example, a seller can request full credit if a buyer backs out and does not buy an item. Fee credit values are returned by GetAccount. Unlike Final Value Fees, however, credits cannot be reported at the order line item level. See Unpaid Item Cases for more information about fee credits.

Due to data processing and storage limitations and performance considerations, neither Final Value Fees nor fee credits are aggregated and reported for items as a whole.

See the Fees Overview on the eBay Web site for information about fees and fee credits.

Fees Overview

For site-specific fee information refer to Fees per Site.