Skip to main content
Published: December 09 2004, 9:03:00 PMUpdated: July 21 2022, 4:17:21 AM

Best Practices for GetSellerEvents and GetSellerTransactions

The following technical note will briefly describe common use cases for GetSellerEvents/GetSellerTransactions and will detail eBay recommended best practices for these functions. eBay Developers may utilize GetSellerEvents, GetSellerTransactions, or a combination of both functions to process post-auction events for the item list of an eBay seller. Post-auction processing may include generating a sales report, finalizing shipping options, generating invoices, etc.

The following notation will be used for the remainder of this article:

GetSellerTransactions/GetItemTransactions = "GST"
GetSellerEvents = "GSE"


** Usage of GSE **

GSE is used to retrieve price changes, item revisions, description revisions, and other changes that have occurred within the last 48 hours related to a seller's eBay listings. The response of a GSE request can be used as input to a post-auction processing algorithm or to generate an activity report for a specified eBay seller. GSE does not return information specific to the sale of the item such as shipping options or the buyer shipping address. GSE should be used only with the most recent time period. Time windows in the past will not include items that have been modified more recently. GSE should not be used for reconciling activity from time periods well in the past. Ideal and efficient GSE usage can be framed as "obtain the events within the listings of a specific seller which have occurred in the last few hours" A GSE event can be framed as "an indication that a property of an item has been modified"

** Best Practices for GSE **

1 - Including a 2 minute buffer

On occasion, due to eBay bandwidth and system usage, post-auction processing may be slightly delayed. Because the finalization of an eBay event may require a few additional cycles of processing, eBay strongly recommends including a 2 minute buffer between the current time and the ModTimeTo filter. As an example, a GSE request executed at 12:00 should specify a ModTimeTo filter of 11:58. By including this buffer, the application may avoid situations in which data is not finalized or completed after an event occurs on eBay. Application developers may elect to increase this buffer size based on their specific requirements.

2 - Executing overlapping request

Errors due to slight delays in eBay processing cycles can also be avoided through usage of overlapping time window requests. An overlapping request window of 2 minutes is recommended by eBay. As an example, a GSE request using the following overlapping windows is an effective defensive algorithm: (10:00 - 10:50) (10:48 - 11:50) (11:48-12:50). Application developers may elect to increase this buffer size based on their specific requirements.

3 - Synchronization with the eBay Official Time

An application should synchronize with the eBay Official Time on each unique session or scheduled execution. Ideally, this synchronization should occur at any unique execution of an application. Synchronization of the GeteBayOfficialTime response and the application time-stamp for the response is a recommended best practice.

4 - Pagination and Recommended intervals (TimeFrom / TimeTo ranges)

At this point you might also be asking what's the catch. It seems like I can get updates for an unlimited number of items in just one API call. Not quite; there are limits to this call. There is a hard limit of 2000 items at DetailLevel ReturnAll and 3000 items at DetailLevel None (no DetailLevel included in the request) for the data returned by GetSellerEvents. Please remember that this call is not paginated, so if there are more items than this limit you will not be getting all of the items. If the number of items in the ItemArray is this hard limit then that probably means there were more items.

Since this call is not paginated and there is a hard limit to the number of items returned, you should tune the frequency of this call based on the listing volume of the seller. Here is a set of recommendations based on the number of active items a seller has:

40000+ active items - at least every 20 minutes
20000-40000 active items - at least every 20 to 30 minutes
10000-20000 active items - at least every 20 to 40 minutes
5000-10000 active items - at least every 45 - 60 minutes
2000-5000 active items - at least every 1 to 6 hours
500-2000 active items - at least every 6 hours

** Sample GSE Algorithm **

SyncronizeeBayClock ( )
...
at 7:00 - GetSellerEvents ( ModTimeFrom = 5:56 , ModTimeTo = 6:58 )
...
at 8:00 - GetSellerEvents ( ModTimeFrom = 6:56 , ModTimeTo = 7:58 )
...
at 9:00 - GetSellerEvents ( ModTimeFrom = 7:56 , ModTimeTo = 8:58 )
...


** Usage of GST **

GST is used to retrieve the transactions for the purchases of items from listings by a particular seller. Transactions contain information related to the sale of an item such as the buyer shipping address and shipping options. GST will not return data which is unrelated to the sale of a particular item. As an example, an item which has ended without a winning bidder will not generate a transaction and will therefore not be returned in GST.

** Best Practices for GST **

1 - Including a 5 minute buffer

On occasion, due to eBay bandwidth and system usage, post-auction processing may be slightly delayed. Because the finalization of an eBay event may require a few additional cycles of processing, eBay strongly recommends including a 5 minute buffer between the current time and the LastModifiedTo filter. As an example, a GST request executed at 12:00 should specify a LastModifiedTo filter of 11:55. By including this buffer, the application may avoid situations in which data is not finalized or completed after an event occurs on eBay. Application developers may elect to increase this buffer size based on their specific requirements.

2 - Executing over-lapping request

Errors due to slight delays in eBay processing cycles can also be avoided through usage of overlapping time window requests. An overlapping request window of 5 minutes is recommended by eBay. As an example, a GST request using the following overlapping windows is an effective defensive algorithm: (10:00 - 10:50) (10:45 - 11:50) (11:45-12:50). Application developers may elect to increase this buffer size based on their specific requirements.

3 - Synchronization with the eBay Official Time

An application should synchronize with the eBay Official Time on each unique session or scheduled execution. Ideally, this synchronization should occur at any unique execution of an application. Synchronization of the GeteBayOfficialTime response and the application time-stamp for the response is a recommended best practice.

** Sample GST Algorithm **

SyncronizeeBayClock ( )
...
at 7:00 - GetSellerTransactions ( LastModifiedFrom = 5:50 , LastModifiedTo = 6:55 )
...
at 8:00 - GetSellerTransactions ( LastModifiedFrom = 6:50 , LastModifiedTo = 7:55 )
...
at 9:00 - GetSellerTransactions ( LastModifiedFrom = 7:50 , LastModifiedTo = 8:55 )
...

How well did this answer your question?
Answers others found helpful

Got thoughts? Click the feedback button – your insights help us improve!