Subscribing to and retrieving eBay notifications

eBay has two API-enabled notification platforms. One is REST-based and requires integration with the Notification API, where users can view a list of topics, set up an endpoint to receive notifications, and subscribe to those topics. The other is XML-based and will require the use of the SetNotificationPreferences call to subscribe to notifications and set up an endpoint to receive these notifications.

Subscribing to topics with the Notification API

Integrating with eBay's Notification API allows third-party platforms to subscribe to and receive various types of notifications that eBay will send to the user's destination endpoint. General topics and seller-focused topics are summarized below: 

• Marketplace Account Deletion: This notification is sent to a developer when an eBay user has requested that their personal data be deleted and their account closed. For more information, refer to the eBay Marketplace Account Deletion page.
• Authorization Revocation: This notification is sent to a developer when a user revokes permissions for their eBay Developers Program application.
• Priority Campaign Strategy Budget Status: This notification is sent to sellers when their Promoted Listings priority strategy ad campaign’s daily budget has been completely exhausted.
• Seller Standards Profile Metrics: This notification is sent to sellers to inform them about changes or possible changes to their Seller Standards level in any of the seller performance metrics. See the eBay Seller Standards program page in your eBay account for more information on these metrics and the thresholds. 
• Seller Customer Service Metric Rating: This notification is sent to sellers to inform them about critical changes to their Item Not Received or Item Not as Described customer service metrics performance (this includes proactive warnings when their service metrics are trending towards 'very high'). 

The following flow will allow you to start receiving these notifications to your configured endpoint:

1. Use createDestination to set up an endpoint for receiving notifications from eBay. This endpoint is required for handling incoming notification data securely.
2. Use getTopics to retrieve the full list of notification topics available. Pay attention to any OAuth scopes in the authorizationScopes array. Some topics require special scopes; if you lack the necessary scope(s), you cannot subscribe to that topic. Also, note the topicId values, as these are required to subscribe to those topics.
3. Use createSubscription to subscribe to a topic. Specify the topicId value for the topic, the endpoint that will receive these notifications, and set the status value to ENABLED.
4. For every notification sent to the endpoint, extract the Base64-encoded X-EBAY-SIGNATURE header included in the eBay notification. Pass this value as a path parameter in the getPublicKey method. The key value returned in the response is used to validate the eBay push notification message payload.
5. Take whatever action is needed (if any) based on the notification.

Below are some of the other supporting methods of the Notification API:

• The destination resource has the following additional methods available:
• Use getDestination to retrieve details about one specific destination endpoint.
• Use getDestinations to retrieve all configured destination endpoints.
• Use updateDestination to make updates to a destination endpoint.
• Use deleteDestination to delete a disabled destination endpoint.
• The subscription resource has the following additional methods available:
• Use getSubscriptions to obtain details about all notification topic subscriptions. Use updateSubscription to modify an existing subscription.
• Use enableSubscription to enable previously disabled topic subscriptions and use disableSubscription to disable active topic subscriptions.
• Use testSubscription to send a test notification and verify the subscription's functionality.
• Use deleteSubscription to remove a subscription, stopping notification delivery for that topic.
• Utilize createSubscriptionFilter to set up filters for topic subscriptions, ensuring notifications are aligned with specific criteria.
• Employ getSubscriptionFilter to access detailed information about a particular filter, such as its criteria, status, and creation date.
• Use deleteSubscriptionFilter to deactivate and remove an active filter, enabling the creation of a new filter with revised criteria.
• The getConfig method will retrieve the email associated with the application, and the updateConfig method can update the email associated with the application.

Subscribing to Platform Notification events

Integrating with eBay's Trading API enables users to subscribe to and manage various platform notifications triggered by specific eBay events. Below are some of the key seller-focused event types and their purpose:

• FixedPriceTransaction: this notification is sent each time a seller has a sale on a multiple-quantity, fixed price listing.
• ItemSold: this notification is sent when a fixed price listing ends with a purchase or an auction listing ends with a winning bidder.
• BestOffer: this notification is sent when a seller receives a Best Offer from a buyer.
• BidReceived: this notification is sent each time a qualifying bid is received for an auction listing.
• BuyerCancelRequested: this notification is sent when the buyer has requested that the order be cancelled. 
• ReturnCreated: this notification is sent when the buyer has created a return request for the item. 
• ItemOutOfStock: this notification is sent when the quantity of a fixed price listing has reached ‘0’. This notification will only be sent if the seller is opted into Out-of-Stock control.
• AskSellerQuestion: this notification is sent if a buyer has asked the seller a question about an active listing.

For a complete list of available notification event types, refer to NotificationEventTypeCodeType. Detailed information about these event types is available in the Platform Notifications guide. 

The Trading API has the following calls to subscribe to and manage platform notifications:

• Utilize the SetNotificationPreferences call to subscribe to specific notification event types. Define the destination for these notifications, such as an email address or a URL endpoint.
• Employ the GetNotificationPreferences call to retrieve your current notification preferences. This enables you to confirm the event types you are subscribed to and review your notification delivery settings. Proper configuration is essential for receiving the appropriate notifications.
• Utilize the GetNotificationsUsage call to access details about the notifications that have been sent to you. Reviewing this information allows you to evaluate whether your notification setup is working as intended and determine if any adjustments are needed.

Sending discounted offers to interested buyers

The Negotiation API is used to help sellers identify items eligible for special offers and engage potential buyers by sending them discounted offers. By targeting buyers who have shown interest in specific listings, sellers can enhance their chances of closing sales.

• Utilize findEligibleItems to pinpoint listings that are eligible for seller-initiated offers.
• Use sendOfferToInterestedBuyers to present discounted offers to buyers who have expressed interest in these eligible listings.

Managing buyer/seller communications

Facilitating effective communication between buyers and sellers is crucial for smooth transactions on eBay. This use case outlines the methods available to enable message exchanges between buyer and seller, and to retrieve and manage eBay InBox messages and folders.

The API calls for managing buyer/seller communications are discussed below:

• Use AddMemberMessageAAQToPartner to enable a buyer and a seller in an order relationship to send messages to each other's My Messages Inboxes, fostering direct communication.
• Use AddMemberMessageRTQ to allow a seller to reply to a buyer's question about an active item listing, ensuring prompt responses to inquiries.
• Use AddMemberMessagesAAQToBidder to enable a seller to send up to 10 messages to bidders or users who have made offers via Best Offer, regarding an active item listing, facilitating communication with potential buyers.
• Use GetUserContactDetails to return contact information for a specified user, provided there is a bidding relationship (as either a buyer or seller) between the caller and the user, aiding in direct communication when necessary.

The API calls for retrieving and managing eBay InBox messages and folders are discussed below:

• Use GetMyMessages to retrieve information about the messages sent to a user, providing an overview of all communications received. This call has multiple filters available to control which messages are returned, including date range filters, message folder IDs, or message IDs.
• Use GetMemberMessages to retrieve a list of messages buyers have posted about your active item listings, allowing sellers to address buyer inquiries and concerns.
• Use GetMessagePreferences to return a seller's Ask Seller a Question (ASQ) subjects, each in its own Subject field, enabling sellers to view their current message preferences.
• Use SetMessagePreferences to enable a seller to add, remove, or modify custom Ask Seller a Question (ASQ) subjects, or to reset any custom subjects to their default values.
• Use ReviseMyMessages to mark messages as Read, to flag or unflag messages, and/or to move all specified messages into a different InBox folder.
• Use ReviseMyMessagesFolders to create a new folder, rename an existing folder, or delete an empty folder.
• Use DeleteMyMessages to delete selected messages for a given user.

Handling feedback

Effectively managing transaction feedback is crucial for enhancing transparency and trust between buyers and sellers on eBay. This use case outlines the methods available for retrieving, submitting, and responding to feedback, ensuring smooth feedback exchanges and maintaining a positive reputation.

The API calls to manage transaction feedback are discussed below:

• A seller can use GetFeedback to retrieve Feedback entries they received from a buyer or Feedback entries they left for a buyer. This call also retrieves detailed Feedback ratings and metrics for the seller.
• The GetItemsAwaitingFeedback call will return all sales transactions where the seller has yet to leave Feedback for the buyer.
• A seller uses LeaveFeedback to provide Feedback to the buyer for a specific sales transaction.
• Use RespondToFeedback to address feedback or include follow-up remarks. This allows sellers to clarify any issues or express appreciation, further enhancing buyer-seller relationships.

• Regularly use getSubscriptions to audit and manage your active subscriptions, ensuring they align with your current notification needs.
• Use createSubscriptionFilter to refine notifications based on specific criteria, reducing unnecessary data processing.
• Periodically review all configured endpoints with getDestinations to ensure they are up-to-date and secure.
• Test endpoints using testSubscription to confirm they are correctly receiving notifications.
• Always validate incoming notification payloads using the getPublicKey method to ensure they are genuine and untampered.