This document gives you an overview of the Client Alerts API, answers common questions, and points you to other resources where you can learn more.
Client Alerts API users should be familiar with the Trading API, and to know about application keys and user tokens.
The eBay Client Alerts API makes it easy to receive near real-time seller and buyer alerts about events on the eBay site. It offers the following:
If you make frequent calls to Trading APIs to update your application with events on the eBay site, you should consider using the Client Alerts API, because is a quick, lightweight alternative to those API calls. The load on your servers (and eBays') will be much lighter.
It's likely that you'll want to build applications that combine the Client Alerts API with another API. For example, a Trading API application might use functionality from the Client Alerts API to monitor and manage user listings, and a Shopping API application might use Client Alerts functionality to provide alerts to bidders.
Shopping and Trading API applications include item sales management which can include integration with database inventory systems, item search utilities, user account management systems, systems that embed partner item listings in their Web pages, and applications that assist buyers in managing the listings they're interested in. The Client Alerts API is only for retrieving alerts about events on the eBay site.
Note that Client Alerts and Platform Notifications are mutually exclusive, and you specify either the Client Alerts protocol or the Platform Notifications protocol for an entire application. If your application currently relies on Platform Notifications, you should not test Client Alerts in production. If you do, your application will stop receiving Platform Notifications until you reset the application setting.
This table compares the Client Alerts API to eBay Platform Notifications.
| Client Alerts | Platform Notifications |
|---|---|
| Pull: applications retrieve alerts by making a Client Alerts API call (usually a series of calls at brief intervals) | Push: applications receive subscribed alerts |
| Input is URL name/value pairs; output is JavaScript Object Notation (JSON) | Input is XML or SOAP; output is SOAP |
| Depending on alert type, may or may not require subscription and session login | Requires subscription |
| Small payload | Requires a server that can receive SOAP messages at a notification delivery URL |
| Optimal for web client applications | Optimal for server applications |
| List of available events: see below | List of available events: see the Platform Notifications Guide |
You can retrieve two different kinds of alerts: public alerts, and user alerts.
Public alerts are about public events that occur on the eBay site, and any user can retrieve a public alerts such as PriceChanged and ItemEnded.
Public alerts are retrieved by specifying an item and making a request for alerts about public events on that item. For example, using the ItemID of a listing of a signed first edition of Harry Potter and the Philosopher's Stone, a public alert request retrieves any alerts that the item's price has changed.
Public alerts are available to both sellers and buyers. Available alerts:
GetPublicAlerts: anonymously polls public events on the eBay site.
See the Call Reference for details.
User alerts are about events that affect a particular user. To receive them, user first subscribes to the events using the Trading API call SetNotificationPreferences. The user then uses the Client Alerts Login call to create a session, and includes session data in the Client Alerts API GetUserAlerts call. This user can retrieve any user alerts to which he or she has subscribed. For example, a seller who listed a UK first edition of the book "Harry Potter and the Philosopher's Stone" and a watch with a Gryffindor crest subscribes to be alerted when either of her listed items are bid on, or when the price changes on either item. If a buyer subscribes to Outbid notices, the Client Alerts API will return, when polled, Outbid alerts for all items the buyer has bid on.
Available user alerts for buyers and sellers (note that both public alerts are available as user alerts):
| For Sellers | For Buyers | For Both |
|---|---|---|
| EndOfAuction | WatchedItemEndingSoon | PriceChange |
| FixedPriceEndOfTransaction | Outbid | ItemEnded |
| FixedPriceTransaction | ItemAddedToWatchList | FeedbackReceived |
| BidReceived | ItemRemovedFromWatchList | FeedbackLeft |
| ItemSold | SecondChanceOffer | FeedbackStarChanged |
| ItemUnsold | BidPlaced | |
| AskSellerQuestion | ItemWon | |
| BestOffer | ItemLost | |
| BestOfferPlaced | BestOfferDeclined |
GetUserAlerts: polls user events on the eBay site.
See the Call Reference for details.
Yes, you can. The Client Alerts API is optimized to retrieve information from the live eBay site and you can test your application there. Or, you can use the Sandbox to add or find items, stage alert-triggering events on them, and retrieve the alerts. Test your Client Alerts API calls by posting them to https://clientalerts.sandbox.ebay.com/ws/ecasvc/ClientAlerts?.
Read about the eBay Sandbox at the eBay sandbox.
This section describes the Client Alerts API, how events trigger alerts, and how to retrieve public and private alerts.
When an event takes place on the eBay site (a buyer places a bid, or a listing ends), a new alert is generated and stored on an eBay server. A Client Alerts application polls the eBay server for an event, and retrieves the alert.
Public alerts about an item are stored until two hours after the item's listing ends.
User alerts are stored until two hours after the event.
Public events require no subscription or session. To retrieve a public alert about an item:
Note that the Client Alerts server does not begin storing alerts about an item until the first request for alerts about the item. So your first call may retrieve an alert if another user has already requested alerts about events on the same item.
To retrieve user alerts, the application representing the user does the following:
Note that the Client Alerts server does not begin storing alerts about a user's events until the user has subscribed to the events.
To get a Client Alerts token, use the Trading API call GetClientAlertsToken, and pass in the user's user token. This is the same user token that authorizes an application to use the Trading API on a user's behalf. Note that the retrieval of a Client Alerts user token does not require your users to repeat the process of getting a Trading API user token, and does not require the user's password. If you need a user token, you can get one using your keys here: https://developer.ebay.com/DevZone/account/tokens/.
Client alerts tokens remain valid for seven days, after which they need to be replaced. Third-party developers who want to renew expired Client Alerts tokens for all the users of a third-party application will be able to do so programmatically, simply by making the GetClientAlertsToken call.
Client Alerts session information (SessionID and SessionData) authenticates the user and application, and also time-stamps the Client Alerts API calls that retrieve alerts. SessionData is refreshed at each call for user alerts, so that that the user making a series of calls receives only fresh alerts.
To retrieve the SessionID and SessionData values you need to submit in exchange for private alerts, use the Client Alerts API Login call, passing in your Client Alerts token. SessionID and SessionData are returned.
The Client Alerts service generates alerts when events occur on the eBay site, and stores these alerts on an eBay server. Alerts are generated for public events in which users have expressed interest, and for user events to which users have subscribed. The server stores alerts about public events for at least two hours after an item ends, and alerts about user events for at least two hours after they occur. Third-party applications that use the Client Alerts API retrieve these stored alerts by polling the Client Alerts API at intervals. This section briefly outlines some recommendations for how to set your application's polling intervals.
Nonvarying Polling Interval: If you are setting an unvarying polling interval in your application, it is recommended that you set the interval so that your application polls Client Alerts at least once every five minutes.
Smart Polling Interval: The Client Alerts API may be more useful to your users if you set a smart polling interval that varies over the course of the auction. You might poll less frequently than for an unvarying polling interval, (once every five to ten minutes, for example) until, say, one hour before the end of auction, and then poll once a minute for last 59 minutes, and then poll every ten seconds for the final minute.
Client Alerts API calls are in URL format, with name/value pairs.
This is a picture of the components of a request for public alert. The ChannelType is a generic field that is a container for entities on which events can happen. Currently, Item is the only available ChannelType.
Call Building Blocks (URL-format input, HTTP Get)
This is a picture of the components of a user alert, which is authenticated and time-stamped by the SessionID and SessionData.
Call Building Blocks (URL-format input, HTTP Get)
See Making a Client Alerts API Call for a detailed description of the components of a Client Alerts API call.
| Object | Longevity |
|---|---|
| eBay User Token | 18 months |
| eBay Client Alerts Token | One day |
| Client Alerts session ID (for retrieving user alerts) | 24 hours |
| Public alert | Retrievable until two hours after item ends |
| Private alert | Retrievable until approximately two hours after the alert-triggering event |
Client alerts are sent in JSON format. There are a lot of things you can do with the alerts you get back from eBay. You can use them for informational goals, or to trigger an event, or to trigger a call using one of the other APIs.
"Build":"e563_core_Bundled_6551139_R1","Version":"563","Content":[{"ChannelID":"280225144418","ChannelType":"Item",
"ChannelEvent":[{"EventType":"PriceChange","PriceChange":{}}],"LastModifiedDate":"2008-05-09T19:08:46.000Z"}]}
eBay also offers a JavaScript Toolkit and a Flash Toolkit to make it easier to work with these formats.
You can obtain more information about the eBay Client Alerts API at these locations:
© 2008 eBay Inc. All rights reserved.