The eBay Buy Communication APIs help buyer-facing applications keep buyers informed and connected throughout post-discovery and post-transaction workflows. These APIs can be used to receive buyer-relevant eBay notifications, manage conversations between buyers, sellers, and eBay, and retrieve, leave, or respond to transaction feedback.

This guide covers the following Commerce APIs:

• Feedback API: Retrieves items awaiting feedback, retrieves feedback records, submits feedback for an order partner, returns feedback rating summaries, and responds to feedback.
• Message API: Sends messages, retrieves conversations, retrieves a specific conversation, and updates conversation status.
• Notification API: Retrieves notification topics, configures alert settings, creates destinations, creates subscriptions, tests subscriptions, and validates notification payloads.

This guide is focused on Buy communication workflows. It does not include the seller-initiated discounted-offer workflow, because discounted offers to interested buyers are handled by the Negotiation API and are not relevant to buyer-facing Buy Communications integrations.

Subscribing to and retrieving eBay notifications
Managing buyer/seller communications
Handling feedback

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 requires 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. For buyer-facing communication workflows, applications should focus on topics that can be subscribed to on behalf of buyers or topics that apply to both buyers and sellers. For the complete list of supported Buy notification events, see Buy notification events.

Buyer-relevant topics are summarized below:

• New Message: This notification is sent when a buyer or seller receives a new message from eBay or another eBay user.
• Feedback Left: This notification is sent when feedback left by the buyer or seller for an order partner has been recorded by eBay.
• Feedback Received: This notification is sent when a buyer or seller receives feedback from an order partner for a line item.
• Feedback Star Rating: This notification is sent when the feedback star rating for a buyer or seller has changed.
• Item Marked Shipped: This notification is sent to a buyer or seller when an item is marked as shipped by eBay or by the seller.
• Auction Activity: This notification can include buyer activity such as a bid placed by the buyer, the buyer being outbid, or the buyer winning an auction item.
• Offer Activity: This notification can include buyer activity such as a seller sending an offer or counteroffer to the buyer.

Do not include seller-only notification topics as core Buy Communication workflows. Examples of seller-only topics include Buyer Question, Buyer Requested Purchase Quote, Order Confirmation, Priority Campaign Strategy Budget Status, Seller Customer Service Metric Rating, Seller Standards Profile Metrics, and Promoted Listings campaign topics. Some listing stream topics, such as Item Availability, Item Price Revision, and Priority Listing Revision, are restricted to approved partner use cases and should not be positioned as standard buyer communication topics unless product guidance confirms they should be covered.

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 or scopes, you cannot subscribe to that topic. Also note the topicId values, as these are required to subscribe to 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 and validate the X-EBAY-SIGNATURE header included in the eBay notification. Use getPublicKey to retrieve the public key needed to validate the eBay push notification message payload.
5. Take whatever action is needed based on the notification. For example, a NEW_MESSAGE notification can trigger retrieval of the conversation thread, and a FEEDBACK_RECEIVED notification can trigger retrieval of the feedback record.

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.
  • Use createSubscriptionFilter to set up filters for topic subscriptions, ensuring notifications are aligned with specific criteria.
  • Use 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 retrieves 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 buyer-focused or buyer/seller event types and their purpose:

• BestOfferDeclined: This buyer-facing notification is sent when a seller declines the buyer's Best Offer on an item.
• BestOfferPlaced: This buyer-facing notification is sent each time a prospective buyer places a Best Offer on an item.
• BidItemEndingSoon: This notification is sent to a subscribed buyer when the auction item where the buyer has an active bid is about to end.
• BidPlaced: This buyer-facing notification is sent when the buyer places a bid for an auction item.
• CounterOfferReceived: This buyer-facing notification is sent when a seller makes a counteroffer to the buyer's Best Offer on an item.
• Feedback: This notification is applicable to both buyers and sellers and is sent when the user has left feedback for, or received feedback from, the other party in the order.
• FeedbackLeft: This notification is applicable to both buyers and sellers and is sent when the user leaves feedback for an order partner.
• FeedbackReceived: This notification is applicable to both buyers and sellers and is sent when the user receives feedback from an order partner.
• FeedbackStarChanged: This notification is applicable to both buyers and sellers and is sent when the user's feedback star level changes.
• ItemAddedToWatchList: This buyer-facing notification is sent when the buyer adds an item to the Watch List.
• ItemLost: This buyer-facing notification is sent if the buyer did not end up as the highest bidder for an auction item.
• ItemMarkedPaid: This notification is sent to a subscribed buyer and seller when the seller has marked an order as paid.
• ItemMarkedShipped: This notification is sent to a subscribed buyer and seller when the seller has marked an item as shipped.
• ItemReadyForPickup: This notification is sent to a subscribed buyer when an In-Store Pickup or Click and Collect order is ready to be picked up.
• ItemRemovedFromWatchList: This buyer-facing notification is sent when the buyer removes an item from the Watch List.
• ItemWon: This buyer-facing notification is sent if the buyer is the winner of an auction item.
• MyMessageseBayMessage: This notification is sent to a subscribed buyer or seller when eBay sends a message to that user's InBox.
• MyMessagesM2MMessage: This notification is sent to a subscribed buyer or seller when another eBay user sends a message to that user's InBox.
• OutBid: This buyer-facing notification is sent when another buyer has outbid the subscribed buyer on an auction listing.
• PaymentReminder: This notification is sent to a subscribed buyer if payment is still due for an order.
• ReturnCreated: This notification is applicable to both buyers and sellers and is sent when a return request involving those users is created.
• ReturnClosed: This notification is applicable to both buyers and sellers and is sent when a return request is closed.
• ReturnShipped: This notification is applicable to both buyers and sellers and is sent when the buyer has shipped a return item back to the seller.
• ShoppingCartItemEndingSoon: This notification is sent to a subscribed buyer when an item in the buyer's shopping cart is about to end.
• WatchedItemEndingSoon: This buyer-facing notification is sent when a listing that the buyer is watching is ending soon.

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:

• Use 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.
• Use 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.
• Use 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.

Managing buyer/seller communications

Managing communications using the Message API

The Message API allows users to send messages, retrieve conversations, and modify the status of conversations.

Sending a message:

The sendMessage method can be used to start a conversation with another user, or send a message in an existing conversation.

When sending a message through the sendMessage method, the messageText field is required to specify the content of the message. One of the following fields is also required to specify whether the message is being sent in an existing conversation or to start a new conversation:

• conversationId: The identifier of the existing conversation for which to send the message. This field is required if sending a message in an existing conversation. This ID can be retrieved using the getConversations method.
• otherPartyUsername: The eBay username of the intended recipient of the message. This field is required if starting a new conversation with another eBay user.

Additionally, optional information can be attached to a message through the following containers:

• messageMedia: This container can be used to attach media files to a message. Up to five forms of media can be sent per message. The following types of media can be attached to a message:
  • IMAGE
  • PDF
  • DOC
  • TXT
• reference: This container can be used to specify that a message is referencing a specific eBay listing. The type of reference can be specified through the referenceType field, while the identifier of the reference can be specified through the referenceID field. Currently, only listings are supported, so the referenceType will always be LISTING, and the referenceID will be the item ID value of the listing.

A successful call sends the message based on the provided information and returns details about the message, such as its creation date and message ID value.

Updating a conversation:

The updateConversation and bulkUpdateConversation methods can be used to update the status of one or more conversations. This includes the conversation status, such as whether it is active, archived, or deleted, as well as the read status, such as whether it has been marked as read or unread.

When updating a conversation through these methods, the following fields are required in the request payload to specify the conversation or conversations being updated:

• conversationId: The unique identifier of the conversation that is to be updated. The getConversations method can be used to retrieve this value.
• conversationType: The existing conversation type of the conversation being updated. This value cannot be updated through this method, but is required as part of the request payload. The following string values are supported:
  • FROM_MEMBERS: This string value indicates that the conversation is with another eBay member, such as a buyer or seller.
  • FROM_EBAY: This string value indicates that the conversation is with eBay itself.

Once the conversation ID and type are specified, the status of the specified conversation or conversations can then be updated. Using these methods, either the conversation status or read status of a conversation can be changed.

Important: Only the conversation status or read status of a conversation can be changed at a time per call.

The following fields can be used to update the status of a conversation:

• conversationStatus: The status for which to update the specified conversation. The following string values are supported:
  • ACTIVE: Updates the conversation to active status, meaning that it is a currently active conversation with an eBay member or eBay itself.
  • ARCHIVE: Updates the conversation to archive status, meaning that it will be archived but not deleted. Archived conversations are stored and can be moved back to active status using this method if needed.
  • DELETE: Updates the conversation to delete status, meaning that it will be deleted. Deleted conversations cannot be recovered.
  • READ: Updates the conversation to read status, meaning that it will be shown as being read by the recipient. Note that there is a separate read boolean field in the updateConversation method that handles this function.
  • UNREAD: Updates the conversation to unread status, meaning that it will be shown as unread by the recipient. Note that there is a separate read boolean field in the updateConversation method that handles this function.

A successful call updates the status of the conversation or conversations to the specified status.

Retrieving conversations:

The getConversation and getConversations methods can be used to retrieve messages within one or more conversations.

The getConversation method can be used to retrieve messages within a specified conversation. The conversation from which to retrieve messages is specified by its conversation_id value. The type of the conversation must also be specified through the conversation_type query parameter. If the call is successful, details about each message within the specified conversation that meet the specified filter criteria are returned. This can include information such as the message text and ID, its read status, and the usernames of the sender and recipient.

Alternatively, the getConversations method can be used to retrieve up to 10 conversations. The following query parameters are available to refine your conversation search:

• conversationStatus: The status of the conversations being retrieved. Only conversations in the specified status are retrieved. Supported values include ACTIVE, ARCHIVED, DELETED, READ, and UNREAD.
• conversation_type: The type of conversations being retrieved. Only conversations of the specified type are returned. Supported values include FROM_EBAY and FROM_MEMBERS.
• reference_id: The unique identifier of the reference, such as the item ID value, associated with the conversation. Only conversations referencing the specified value are returned.
• reference_type: The type of reference, if any, associated with a conversation. For example, a value of LISTING specifies that the conversation is associated with a specific listing. Currently, only LISTING is supported.
• start_time and end_time: Only conversations sent between this time period are returned.
• other_party_username: The username of an eBay user for which to retrieve conversations. Only conversations with this specified user are returned.

The following pagination parameters are available to control the amount of data returned in the response payload:

• limit: Specifies the number of items from the result set returned on a single page.
• offset: Specifies the number of items to skip in the result set.

Managing communications using the Trading API

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 buyers and sellers, 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 through Best Offer regarding an active item listing.
• 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.

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 communications received. This call has multiple filters available to control which messages are returned, including date range filters, message folder IDs, and message IDs.
• Use GetMemberMessages to retrieve a list of messages buyers have posted about active item listings, allowing sellers to address buyer inquiries and concerns.
• Use GetMessagePreferences to return a seller's Ask Seller a Question 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 subjects, or to reset any custom subjects to their default values.
• Use ReviseMyMessages to mark messages as read, flag or unflag messages, or move 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

Effective feedback management builds transparency and trust between buyers and sellers on eBay. This use case explains how to retrieve, leave, and respond to feedback to keep transactions smooth, resolve issues, and maintain a positive reputation. You can use the Feedback API REST API, or the Trading API legacy API to handle feedback.

Using the Feedback API

The Feedback API manages transaction feedback through the methods contained in the following table.

Method	Description
getItemsAwaitingFeedback	Retrieves a filtered list of line items for which feedback is pending from the user based on their role.
getFeedback	Retrieves a filtered list of line items for which feedback is available from the user based on their role. This method also retrieves detailed metrics for sellers.
leaveFeedback	Submits feedback associated with a line item for an order partner, generating a unique ID for tracking and reference purposes.
respondToFeedback	Responds to feedback provided by the order partner on a specific line item in an order.
getFeedbackRatingSummary	Returns a categorized summary of feedback metrics for an eBay seller, filtered by criteria.

The following scenarios describe key uses:

• Get items awaiting feedback

To retrieve a list of items that still require feedback, whether acting as buyer or seller, call the getItemsAwaitingFeedback method.

• Retrieve feedback

Use the getFeedback method to gather feedback for a specified user, with filtering options based on transaction, item, comment type, AI-filtered topics, or feedback containing photos. This method also retrieves detailed metrics for sellers. With this in mind, this method supports various feedback retrieval scenarios:

• All feedback for a user
• Feedback received by the user
• Feedback left by the user
• Specific feedback entries
• Feedback on a particular listing or line item
• Feedback of a specific type
• Feedback for the user acting as either a seller or a buyer

• Retrieve AI-filtered feedback

You can specify a topic and have AI generate any associated applicable feedback items through the getFeedback method. Specify the topic and then only feedback for those listings is returned. For example, to have AI generate and return the last 30 days of positive feedback items associated with shipping as a seller, use filter=commentType:POSITIVE,topics:shipping,period:30,role:SELLER. See the topics value in the filter query parameter for specific topics available.

• Leave feedback

Buyers and sellers submit feedback for completed line items by calling the leaveFeedback method.

• Get feedback rating summary

To return aggregated feedback metrics for review, call the getFeedbackRatingSummary method. These ratings are only for sellers and can return metrics like on-time delivery, shipping costs, and communication.

• Respond to feedback received

Buyers and sellers can reply to feedback left by their order partner by calling the respondToFeedback method.

• Using rating templates

Rating templates, if used, define the feedback rating options available for transactions, covering key aspects like on-time delivery and overall experience, and open comments. Detailed seller ratings are only applicable when buyers leave feedback for sellers. Each rating specifies the label presented to users, whether the field is required, the enabled status, and the format of accepted input, such as predefined choices, range, or free text. Call the getItemsAwaitingFeedback method to return any available rating templates. See the following for examples of rating templates returned.

PREDEFINED yes/no rating type for ON_TIME_DELIVERY

{
  "ratingKey": "ON_TIME_DELIVERY",
  "ratingLabel": "Did this item arrive on time?",
  "required": false,
  "ratingValueType": "PREDEFINED",
  "enabled": true,
  "acceptableValues": [
    {
      "value": "2",
      "valueLabel": "Yes",
      "enabled": true
    },
    {
      "value": "3",
      "valueLabel": "No",
      "enabled": true
    }
  ]
}

PREDEFINED with positive, neutral, and negative feedback for OVERALL_EXPERIENCE

{
  "ratingKey": "OVERALL_EXPERIENCE",
  "ratingLabel": "How was your experience?",
  "required": true,
  "ratingValueType": "PREDEFINED",
  "enabled": true,
  "acceptableValues": [
    {
      "value": "POSITIVE",
      "valueLabel": "Positive",
      "enabled": true
    },
    {
      "value": "NEUTRAL",
      "valueLabel": "Neutral",
      "enabled": true
    },
    {
      "value": "NEGATIVE",
      "valueLabel": "Negative",
      "enabled": true
    }
  ]
}

FREETEXT rating type for OVERALL_EXPERIENCE_COMMENT

{
  "ratingKey": "OVERALL_EXPERIENCE_COMMENT",
  "ratingLabel": "What else would you add?",
  "maximumCharactersAllowed": 500,
  "required": true,
  "ratingValueType": "FREETEXT",
  "enabled": true
}

RANGE rating type that takes values between 1 and 5 for DSR_ITEM_AS_DESCRIBED

{
  "ratingKey": "DSR_ITEM_AS_DESCRIBED",
  "ratingLabel": "Item description",
  "required": false,
  "ratingValueType": "RANGE",
  "enabled": true,
  "acceptableValues": [
    {
      "value": "1",
      "valueLabel": "Very inaccurate",
      "enabled": true
    },
    {
      "value": "2",
      "valueLabel": "Inaccurate",
      "enabled": true
    },
    {
      "value": "3",
      "valueLabel": "Neither inaccurate nor accurate",
      "enabled": true
    },
    {
      "value": "4",
      "valueLabel": "Accurate",
      "enabled": true
    },
    {
      "value": "5",
      "valueLabel": "Very accurate",
      "enabled": true
    }
  ]
}

Using the Trading API to manage feedback

The following API calls manage transaction feedback through the Trading API:

• Use GetFeedback to retrieve feedback entries a user received from an order partner or feedback entries the user left for an order partner. This call also retrieves detailed feedback ratings and metrics for sellers.
• Use GetItemsAwaitingFeedback to retrieve completed transactions where the user has yet to leave feedback for the order partner.
• Use LeaveFeedback to provide feedback to the order partner for a specific transaction.
• Use RespondToFeedback to address feedback or include follow-up remarks. This allows users to clarify issues or express appreciation, further supporting buyer-seller relationships.

• If createDestination or updateDestination fails with an invalid endpoint error, confirm that the endpoint uses HTTPS and does not contain localhost or an internal IP address.
• If createDestination or updateDestination fails with an invalid verification token error, confirm that the verification token is 32 to 80 characters long and contains only alphanumeric characters, underscores, and hyphens.
• If createSubscription fails because of an invalid topicId or missing authorization scope, call getTopics again and verify the topic ID, schema version, payload format, and authorizationScopes. For this Buy guide, do not subscribe to seller-only topics unless product guidance explicitly approves them.
• If notification payload validation fails, confirm that the X-EBAY-SIGNATURE header is present and correctly extracted, then use getPublicKey to retrieve the public key and validate the payload before processing the notification.
• If getItemsAwaitingFeedback returns no records for a buyer, confirm that the request uses a buyer-authorized token and the filter=userRole:BUYER filter. An empty response can also mean that the buyer has no purchased items currently awaiting feedback.

• Use getTopics before creating subscriptions so your application uses the current topic IDs, schema versions, payload formats, and authorization scopes.
• For buyer-facing workflows, subscribe only to buyer-relevant or buyer/seller notification topics, such as NEW_MESSAGE, FEEDBACK_LEFT, FEEDBACK_RECEIVED, FEEDBACK_STAR_RATING, and ITEM_MARKED_SHIPPED. Avoid seller-only topics such as order confirmation, buyer question, seller standards, seller customer service metric, and promoted listings campaign topics.
• Use testSubscription before relying on a new subscription in production, and periodically use getSubscriptions and getDestinations to audit active subscriptions and configured endpoints.
• Always validate incoming notification payloads with the X-EBAY-SIGNATURE header and getPublicKey, or use one of the eBay Event Notification SDKs to handle validation.
• For feedback workflows, call getItemsAwaitingFeedback before displaying a leave-feedback form. Use the returned rating templates to build valid buyer feedback requests, and treat feedback as line-item-level data rather than order-level data.