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:
- GetOrders—this call returns all orders in which the authenticated caller is a buyer or seller. The
types of orders returned include single line item orders, multiple line item orders, and Half.com
orders. The caller may filter by OrderID, order role, or order status. The caller can also restrict
the results to Half.com orders. Finally, there are time filters to restrict results based on order
creation time (date range and number of days since creation) 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 time filters, including order creation time (number of days since creation) 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 ItemID, 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 time filters, including order creation time (number of days since creation) 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 time filters
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 Half.com 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:
- 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 and perform the following checks:
- 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
Pending, proceed to Step 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.
- 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:
- Change the paid status of an item using the Paid boolean flag. This action will not be available toDE and AT sellers subject to the new payment process.
- 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.
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.
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.