XML Flow Tutorial: Getting Notifications
This tutorial demonstrates how a user gets platform notifications about a listing. The demonstration consists of a series of eBay API calls that subscribe the user to certain notifications and confirm the subscriptions, and also examples of the actual notifications received by the user.
When a step includes an API call, it gives a link to an XML call sample in the Trading API Reference. The samples show how to perform those steps using the API.
This scenario involves two sandbox test users:
- Magical BookSeller, a fictitious seller who wants to get notifications about her eBay inventory
- Bountiful Buyer, a fictitious buyer who triggers notification events for our seller's listing
The scenario shows how Magical BookSeller uses API calls to configure her eBay account to receive certain notifications about her listings.
What's in this Tutorial
This tutorial contains the following sections:
- Complete Source Code
- Before You Begin
- Step 1: Subscribing to Notifications
- Step 2: Receiving Notifications
- Notes and Next Steps
Complete Source Code
The API Flow tutorials use raw XML requests and responses. The XML call samples described in this tutorial can all be found in the Trading API Reference.
Before You Begin
All the calls in the tutorial are performed in the Sandbox environment, using a test user. To make the calls in the tutorial for your own application in the Sandbox, you must:
-
Join the eBay Developers Program and get your application key set.
-
Create your own Sandbox test user with a Sandbox authentication token. See "Using the Sandbox" in the Trading API Guide for more information.
The tutorial has no specific code requirements. You can run the XML samples in the API Test Tool on the eBay Developers Program website (you must log in).
Step 1: Subscribing to Notifications
MagicalBookSeller wants to be notified when certain events affect her eBay listings. She wants a notification that confirms when an item has been listed, a notification that tells her when a buyer has bid on an item, a notification that an auction has ended, and a notification that a buyer has left feedback on a sale.
MagicalBookSeller uses SetNotificationPreferences to subscribe to notifications for events she chooses. For the delivery address she could specify a URL, but she prefers to have the SOAP notifications delivered to her email address. This subscription will be good for all of her listed items.
-
SetNotificationPreferences: subscribe to notifications
-
GetNotificationPreferences: confirm events in the notification subscription
-
GetNotificationPreferences: confirm the delivery preferences in the notification subscription
Now MagicalBookSeller wants to check that all of her notification preferences are as she intends. She will make a couple of GetNotificationPreferences calls to check first that she is subscribed to the right events, and second that her delivery address is correct. She uses GetNotificationPreferences with the preference level set to User to review the events for which she's subscribed.
Now MagicalBookseller will check her the delivery settings in her notification preferences. She uses GetNotificationPreferences with the preference level set to Application to review the delivery settings.
Step 2: Receiving Notifications
This section shows the notifications that the seller, MagicalBookSeller, receives from eBay about events that affect her listings.
This notification returns the same data fields as the GetItem response.
This notification returns the same data fields as the GetItem response.
This notification returns the same data fields as the GetItemTransactions response.
Notes and Next Steps
This section contains notes about the tutorial and suggestions for extending it.
Here are some suggestions for ways you can learn more about the API:
- Get to know the Platform Notifications chapter in the Trading API Platform Notifications Guide call.
- Explore other calls and processes: Listing an Item, Buying an Item, or Completing a Sale.
- Notifications are a great way to get real-time information about events on the eBay site, but you should always use API calls to confirm the data received using notifications. For example, if you have subscribed to AuctionCheckoutComplete notification, you should also set up periodic polling of GetOrders.
- Your application should respond to notifications with a standard HTTP status of 200 OK. Absent this response to a notification, eBay will attempt redelivery, but after a significant number of unacknowledged notifications, eBay may stop sending notifications to your application.
Additional Resources
More information about the Trading API is available at these locations: