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 item 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 and insurance).

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, a qualifying 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 item, 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 item.

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, multiple line item orders, and single 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 and perform the following checks:

  1. Check the OrderArray.Order.CheckoutStatus.Status value for each order. If the value is Complete,then the order is ready for post-sale processing. If the value is CheckoutIncomplete or Pending, proceed to Step 2.
  2. Check the OrderArray.Order.CheckoutStatus.eBayPaymentStatus for each order. If the value isNoPaymentFailure, PayPalPaymentInProcess, or PaymentInProcess (Germany only), the buyer has not paid yet or the payment is in pending mode. If any other value is returned (for example, BuyerCreditCardFailed or BuyeECheckBounced), there is an issue with buyer payment.
  3. Check the other fields in the CheckoutStatus container to troubleshoot a buyer payment issue. For example, check the following:
    • If the value of the CheckoutStatus.PaymentMethod field matches a payment method specified in OrderArray.Order.PaymentMethods.
    • If the value of the CheckoutStatus.PaymentMethod is IntegratedMerchantCreditCard, the CheckoutStatus.IntegratedMerchantCreditCardEnabled field should be present and set to true.

If an order is not completely ready for post-sales processing, you need to allocate the inventory for the order line item(s), but you must wait to complete checkout. Keep in mind that it is also possible than some order information may change when checkout is still incomplete, such as when the buyer changes their shipping address. Item details, such as the ItemID and quantity purchased will not change, so you can manage your inventory while you wait to complete the sale and move on to fulfillment.

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

If during the checkout process, the buyer selects PayPal as the payment method for the item, the buyer is redirected to the PayPal site to effect the payment. There, the buyer may purchase a shipment for the item and the shipping method for this shipment may be different from any the seller specified and may be different from the shipping method selected during the checkout process on the eBay site. (Buyers familiar with the process will typically do one or the other, but not both. However, less experienced buyers might select a shipping method on the checkout page, not knowing that there can also be a shipping process on the PayPal site. Thus applications have to take this possible difference into consideration.)

If the seller has a PayPal account and the item was paid for using PayPal, the seller may use a feature on the PayPal site to print the mailing labels for the item's shipping. When the seller purchases mailing labels, a shipment record is created for the item. This shipment record can also be used in tracking the shipment (by the seller or the buyer) on the PayPal site.

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. For Selling Manager Pro users, the paid and shipped status and time stamps are returned in order line item-retrieval calls like GetSellerTransactions.

Final Value Fees and Credits

When an item is sold, or ends with a winning bid, or is purchased, you are charged a Final Value Fee (FVF). This fee is in addition to the listing fee that was charged when you listed the item. The total cost of selling an item is the listing fee plus the Final Value Fee.

The Final Value Fee applies whether or not you complete the sale with the buyer. The Final Value Fee is returned in all order retrieval calls.

The calculation of the Final Value Fee depends on several things, such as site, type of item, et. 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. Those fees also don't account for credits (such as reserve fee refunds or eBay promotional credits).

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.

Note: 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 Disputes 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.

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.