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.
Subtopics
Retrieving Order Line Item Data and Managing Orders
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:
- GetOrders—this call returns all orders in which the authenticated caller is a buyer or seller. The caller may filter by Order ID, order role, or order status. There are also date filters to restrict results based on order creation time or the last modification date.
- GetSellerTransactions—this call returns all order line items for the seller making the request. The seller can filter results by seller-defined SKU (stock keeping unit) values. The caller can also restrict the results with date filters, including order creation time or the last modification date.
- GetItemTransactions—this call can be used in a variety of ways. It can return all order line items based on a particular listing, return the data for a particular order line item, or can return the order line item data for all variations of a multi-variation, fixed-price listing. The caller can also restrict the results with date filters, including order creation time or the last modification date.
- GetOrderTransactions—this call returns all orders in which the authenticated caller is a buyer or seller. The caller may filter by OrderID, SKU value, or by OrderLineItemID. This call does not have any date filters
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:
- The DetailLevel is set to ReturnAll
- The ModTimeFrom value is set back two minutes from the time you last made the call
- The ModTimeTo value is set to the current time (if this field is omitted, the ModTimeTo value defaults to the current time
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:
- Change the paid status of an item using the Paid boolean flag.
- Change the shipped status of an item using the Shipped boolean flag
- Set the item's shipment tracking information using the Shipment container
- Leave feedback for the buyer using the FeedbackInfo container.
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
https://pages.ebay.com/help/sell/fees.html
For site-specific fee information refer to Fees per Site.