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.
We heard your requests! Several API enhancements
The 653 Version of the Trading API with Developer-Requested API Enhancements is now available!
Enhancements in this release include:
- Shipping: Tracking Number and Carrier Used
- New VerifyRelistItem Call
- VerifyOnly Field for ReviseItem
- GetPromotionalSaleDetails Enhancement to Filter by Status
- Sellers Can Subscribe to Notification for SellerClosedDisputes
- Updates to GetMyeBaySelling
Tracking Number and Carrier Used are now returned by GetOrders and GetOrderTransactions for both Trading and Half.com. On Half.com, you can use the GetOrders and GetOrderTransactions calls to retrieve unshipped Half.com orders, such as orders that the seller has received but has not yet processed.
The new VerifyRelistItem request allows you to preview the response and fees for an item you want to relist, before you make the actual RelistItem call. This call requests and returns the same data as RelistItem (same inputs, same outputs, and same usage rules), but without actually listing the item to an eBay site.
Applications can use this call to test the definition of an item before actually listing it to eBay with RelistItem, reducing item listing-related errors.
You can use the VerifyOnly boolean field with the flag set to 'true', if you want the response to include the calculated listing price change (if there is an increase in the BIN/Start price) but you do not want the values to persist in the database. See ReviseItem for more details.
Including the VerifyOnly field in ReviseItem is similar to using VerifyAddItem or VerifyRelistItem.
GetPromotionalSaleDetails Enhancement to Filter by Status
Previously, Buyers have been able to subscribe to get notified when a seller has closed a listing dispute. Now the Seller can also subscribe to the SellerClosedDisputes notification. For more information, see options for platform notification.
In response to your product feedback, these enhancements have been made to GetMyeBaySelling:
- Listings with variations now return Variation.StartPrice.
- A new OrderStatusFilter in the request enables you to filter SoldList based on whether transactions have been marked as Paid and/or Shipped in My eBay.
Updates to Summer 2009 Release: Part 1 of 2
On July 29, 2009, Laurel posted an announcement about the July 2009 updates. In this two part entry, we highlight the features that were released since then.(For the change details with each API version, see the API Release Notes.)
Because there have been many updates, this topic will be split into two entries.
This first entry includes:
The second entry (to be published on, or around, December 17) will include:
Items with Variations
-  Multi-Variation Listings: GetSellerEvents and Other Enhancements
-  Changes to ListingFeatureDetails and Some Listing Features to Be Removed and Restricted
Selling Manager Applications
- ShippingCarrierUsed: Type Change
- LeaveFeedback and Shipping API Detailed Seller Ratings (DSRs)
- Reminder: Return Policy and Handling Time Required When You Renew GTC Listings
If you would like details on the July 2009 Update, please refer to the following links and to the API Release Notes.
Please see the BestMatchItemDetails API release notes for details.
[1.2.0] New Feature: Gallery Plus Pictures
[1.2.0] Doc changes: Updated Value for SellerBusinessType Item Filter
Reminder of what changed in Best Match (Details)
- New listing performance score for Fixed Price to replace recent sales
- New multi-quantity and single-quantity Fixed Price listings will be given exposure in Best Match
- Titles are more important than ever
- Seller performance continues to count
- Shipping cost continues to count
- No changes to Auction-style listings
- Optimized by category
- As part of the Edit Live Items feature, a new TransactionID field was added to the GetItemRequest call. This new field will allow both Sellers and Buyers to retrieve a listing as it was at the time of a given purchase by invoking GetItem with a TransactionID in the request (even if the seller has made significant revisions to the listing, following the purchase).
- Sellers are also able to make revisions to their multi-quantity fixed price listings after a purchase has been made (currently, Sellers can not change their multi-quantity fixed price listings, after at least one item in the listing has been purchased).
- Sellers are able to view the updated listing for each transaction, but Buyers are only able to view the transactional version of a listing where they are the successful buyer. Past transactional views of an item will be available for up to 90 days from the date the transaction took place.
 Platform Notification changes and client alerts
- Changes to the GetItemTransaction API call may cause a change to the behavior of the following Platform Notifications: EndOfAction, AuctionCheckoutComplete, FixedPriceEndOfTransaction, CheckoutBuyerRequestTotal, FixedPriceTransaction, Checkout, FixedPriceTransactionForSeller, FixedPriceTransactionForBuyer, ItemMarkedAsShipped, and ItemMarkedAsPaid.
- The following Client Alerts may have a behavior change as a result of this project: EndOfAuction, FixedPriceEndOfTransaction, FixedPriceTransaction, ItemSold, and ItemWon. Each notification will now be based on the state of the item (a 'snapshot' of the item) at the time the transaction was created.
Finding API - see the Finding API release notes for details.
[1.1.0] New: Gallery Plus Pictures
[1.1.0] Updated Value for SellerBusinessType Item Filter
[1.0.1] eBay Top-rated Seller
With the launch of the Top-rated Sellers program, buyers can find items listed by the highest quality sellers on eBay based on the feedback of other buyers. The sellerInfo node in the search results (searchResult.item.sellerInfo) for the "findItems" calls now includes the topRatedSeller field to indicate (true or false) whether the seller of an item qualifies as an eBay Top-rated Seller. Additionally, a new TopRatedSellerOnly item filter has been added to limit search results to items listed by Top-rated Sellers only.
Note the following site restrictions:
- The searchResult.SellerInfo.topRatedSeller field in the response for the finding calls is supported for the following sites only: US (EBAY-US), Motors (EBAY-MOTOR), DE (EBAY-DE), AT (EBAY-AT), and CH (EBAY-CH).
- The TopRatedSellerOnly item filter is supported for the following sites only: US (EBAY-US), Motors (EBAY-MOTOR), UK (EBAY-GB), IE (EBAY-IE), DE (EBAY-DE), AT (EBAY-AT), and CH (EBAY-CH).
Top-rated sellers consistently receive highest buyers' ratings, ship items quickly, and have earned a track record of excellent service. eBay regularly reviews the performance of these sellers to confirm they continue to meet the program's requirements. See the Top-rated Sellers page on the eBay site for more information.
Trading API - See the Trading API release notes for details.
 Clarifications in Documentation for Unpaid Item Disputes
- Version 639 release notes surveyed various process changes for Unpaid Item Disputes.
- Support for the old process will be removed around March 2010, so please migrate your UPI dispute code to work with the new process.
- How do you know whether the newer or older process applies to your disputes or not? It is all about the request version. If you created a UPI dispute with a request version lower than 637, the old timelines apply and the various platform notifications for messaging are still supported. But if the request version is 637 or greater, the new timelines apply.
- Further, since AddDisputeResponse can no longer be used (for 637 or greater) for buyer or seller communication, these notifications are no longer triggered: BuyerResponseDispute, SellerRespondedToDispute.
- See Newer versus Older Unpaid Item Disputes Process - a before/after table of facts.
 New Features for 639
- Multiple-Package Details for a Single Item
- Selling Manager Calls: No Integration with eBay.com Is Required
- Unpaid Item Disputes: Process Change
GetSellerEvents now returns variation details in Item.Variations, including StartPrice, Quantity, and QuantitySold, plus SKU and/or VariationSpecifics. Multiple variations are returned together in the same Variations node (similar to GetItem).
December 2, 2009 in Best Practices, Categories and Item Specifics, Client Alerts API, Developer Community, Developer Education, Documentation, Feedback API, Finding API, Large Merchant Services, Platform Notifications API, Shopping API, Trading API | Permalink