May I Take Your Order?
One of my favorite things about coming to DevCon (besides connecting with everyone face-to-face) is the opportunity to hear speakers like ChannelAdvisor's Grant King share their eBay API best practices. Grant's session on processing eBay orders was, well...just what I ordered!
First, a definition: An eBay order contains two or more separate transactions.
Use Platform Notifications for More Timely Processing
If you want to process a purchase very quickly after the buyer has paid (especially if you handle a large number of transactions), Grant suggests using eBay's Platform Notifications, like AuctionCheckoutComplete and FixedPriceEndOfTransaction.
Here's how it works: When a buyer completes checkout, eBay calls GetItemTransactions on your behalf immediately, and then sends you the GetItemTransaction response as the payload in the notification.
In his experience, notifications are close to 100% reliable nowadays, but it's a good idea to also poll periodically to make sure you catch any transactions that were somehow missed.
Poll with Transaction, Order, and Event Calls
If you're polling, use calls like GetSellerTransactions, GetSellerEvents, GetOrders, and/or GetOrderTransactions. Be sure to build in a bit of padding in the ModTime filters, so you don't miss transactions or events.
In the transaction calls, if OrderID is returned, then use GetOrders to make sure you know about all the purchases that were in the order.
Look for PaymentMethodUsed to find out how the buyer paid, and ExternalTransactionID for the PayPal transaction ID (which the seller needs in order to look at the details on PayPal).
He talked about other fields that are also useful to look for, and suggested best practices for using these calls in combination.
When to Get Order Details
You may want to wait until the buyer has paid (completed checkout) before you import and process all the transaction details from eBay.
To figure out when the buyer has paid, look for CheckoutStatus=CheckoutComplete, and eBayPaymentStatus=NoPaymentFailure. (Ignore CompleteStatus).
If you're using Large Merchant Services, the Merchant Data API's SoldReport hs equivalent fields, like BuyerPaymentTransactionNumber for the PayPal transaction ID, and PaymentClearedTime to confirm that the buyer paid.
For more tips on monitoring the payment status, check out answer ID 1048 in eBay's developer knowledge base ("Mapping eBay Checkout & PaymentStatus with PayPal IPN PaymentStatus").
Other Checkout Tips
Grant gave advice on handling shipping, US tax and non-US VAT, and other eBay checkout features; plus things to think about when you verify that your calculations match the values you got from eBay.
Once the items have shipped, send the buyer the tracking number (good communication can help DSRs). Use CompleteSale in the Trading API or SetShipmentTrackingInfo in the Merchant Data API to send eBay the shipment tracking number. eBay needs this for a number of reasons, such as keeping the buyer informed about the status of their purchases, and enabling customer service agents to help users resolve disputes.
Finally, he recommended that you test, test, and test, and then test some more! Test single transactions, orders, and different combinations of shipping and other details.