--- title: Notification API description: "The eBay **Notification API** provides a comprehensive set of resources for developers to manage the entire lifecycle of asynchronous notifications from eBay. Users can browse available notification topics, configure and manage destination endpoints for receiving notifications, create and manage subscriptions to specific topics with optional filtering, and validate the integrity of received message payloads using public keys. The API supports both application-based and user-based subscriptions, utilizing OAuth 2.0 grant flows, and is essential for applications requiring timely updates on events such as order confirmations, listing revisions, feedback received, and user account changes." api_version: 1.0 api_name: notification_api api_type: REST api_group: sell/notification_api source_url: html: https://developer.ebay.com/develop/api/sell/notification_api md: https://developer.ebay.com/develop/api/sell/notification_api.md --- # Notification API API The eBay **Notification API** provides a comprehensive set of resources for developers to manage the entire lifecycle of asynchronous notifications from eBay. Users can browse available notification topics, configure and manage destination endpoints for receiving notifications, create and manage subscriptions to specific topics with optional filtering, and validate the integrity of received message payloads using public keys. The API supports both application-based and user-based subscriptions, utilizing OAuth 2.0 grant flows, and is essential for applications requiring timely updates on events such as order confirmations, listing revisions, feedback received, and user account changes. ## API Methods The following API methods are available: ### getConfig #### GET /config **Description:** This method allows applications to retrieve a previously created configuration. ### updateConfig #### PUT /config **Description:** This method allows applications to create a new configuration or update an existing configuration. This app-level configuration allows developers to set up alerts. **Parameters:** - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. ### createDestination #### POST /destination **Description:** This method allows applications to create a destination. A destination is an endpoint that receives HTTP push notifications. A single destination for all topics is valid, as is individual destinations for each topic. To update a destination, use the **updateDestination** call. The destination created will need to be referenced while creating or updating a subscription to a topic. **Note:** The destination should be created and ready to respond with the expected **challengeResponse** for the endpoint to be registered successfully. Refer to the [Notification API overview](/api-docs/commerce/notification/overview.html) for more information. **Parameters:** - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. ### deleteDestination #### DELETE /destination/{destination_id} **Description:** This method provides applications a way to delete a destination. The same destination ID can be used by many destinations. Trying to delete an active destination results in an error. You can disable a subscription, and when the destination is no longer in use, you can delete it. **Parameters:** - **destination_id** (string) *required* - The unique identifier of the destination to delete. Only disabled or marked down destinations can be deleted, and enabled destinations cannot be deleted. Use **getDestination** or **getDestinations** to see the current status of a destination. ### getDestination #### GET /destination/{destination_id} **Description:** This method allows applications to fetch the details for a destination. The details include the destination name, status, and configuration, including the endpoint and verification token. **Parameters:** - **destination_id** (string) *required* - The unique identifier of the destination to retrieve. Use **getDestinations** to retrieve destination IDs. ### getDestinations #### GET /destination **Description:** This method allows applications to retrieve a paginated collection of destination resources and related details. The details include the destination names, statuses, and configurations, including the endpoints and verification tokens. **Parameters:** - **continuation_token** (string) - This string value can be used to return the next page in the result set. The string to use here is returned in the **next** field of the current page of results. - **limit** (string) - The maximum number of destinations to return per page from the result set. **Min:** 10 **Max:** 100 **Default:** 20 ### updateDestination #### PUT /destination/{destination_id} **Description:** This method allows applications to update a destination. **Note:** The destination should be created and ready to respond with the expected **challengeResponse** for the endpoint to be registered successfully. Refer to the [Notification API overview](/api-docs/commerce/notification/overview.html) for more information. **Parameters:** - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. - **destination_id** (string) *required* - The unique identifier for the destination. ### getPublicKey #### GET /public_key/{public_key_id} **Description:** This method allows users to retrieve a public key using a specified key ID. The public key that is returned in the response payload is used to process and validate eBay notifications. The public key ID, which is a required request parameter for this method, is retrieved from the Base64-encoded **X-EBAY-SIGNATURE** header that is included in the eBay notification. **Important!** The retrieved public key value should be cached for a temporary — but reasonable — amount of time (e.g., one-hour is recommended.) This key should not be requested for every notification since doing so can result in exceeding [API call limits](/develop/apis/api-call-limits) if a large number of notification requests is received. **Note:** For more details about how to process eBay push notifications and validate notification message payloads, see the [Notification API overview](/api-docs/commerce/notification/overview.html). **Parameters:** - **public_key_id** (string) *required* - The unique key ID that is used to retrieve the public key. **Note:** This is retrieved from the **X-EBAY-SIGNATURE** header that is included with the push notification. ### createSubscription #### POST /subscription **Description:** This method allows applications to create a subscription for a topic and supported schema version. Subscriptions allow applications to express interest in notifications and keep receiving the information relevant to their business. Each application and topic-schema pairing to a subscription should have a 1:1 cardinality. You can create the subscription in disabled mode, test it (see the **test** method), and when everything is ready, you can enable the subscription (see the **enableSubscription** method). **Note:** If an application is not authorized to subscribe to a topic, for example, if your authorization does not include the list of scopes required for the topic, an error code of 195011 is returned. **Parameters:** - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. ### createSubscriptionFilter #### POST /subscription/{subscription_id}/filter **Description:** This method allows applications to create a filter for a subscription. Filters allow applications to only be sent notifications that match a provided criteria. Notifications that do not match this criteria will not be sent to the destination. The **filterSchema** value must be a valid [JSON Schema Core document]() (version 2020-12 or later). The **filterSchema** provided must describe the subscription's notification payload such that it supplies valid criteria to filter the subscription's notifications. The user does not need to provide `$schema` and `$id` definitions. When a filter is first created, it is not immediately active on the subscription. If the request has a valid JSON body, the successful call returns the HTTP status code **201 Created**. Newly created filters are in `PENDING` status until they are reviewed. If a filter is valid, it will move from `PENDING` status to `ENABLED` status. You can find the status of a filter using the [getSubscriptionFilter](/develop/api/sell/notification_api#sell-notification_api-subscription-getsubscriptionfilter) method. See [Creating a subscription filter for a topic](/api-docs/commerce/notification/overview.html#create-filter) for additional information. **Note:** Only one filter can be in **ENABLED** (which means active) status on a subscription at a time. If an **ENABLED** filter is overwritten by a new call to **CREATE** a filter for the subscription, it stays in **ENABLED** status until the new **PENDING** filter becomes the **ENABLED** filter, and the existing filter then becomes **DISABLED**. **Parameters:** - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. - **subscription_id** (string) *required* - The unique identifier of the subscription for which a filter will be created. ### deleteSubscription #### DELETE /subscription/{subscription_id} **Description:** This method allows applications to delete a subscription. Subscriptions can be deleted regardless of status. **Parameters:** - **subscription_id** (string) *required* - The unique identifier of the subscription to delete. Use **getSubscriptions** to retrieve subscription IDs. ### deleteSubscriptionFilter #### DELETE /subscription/{subscription_id}/filter/{filter_id} **Description:** This method allows applications to disable the active filter on a subscription, so that a new subscription filter may be added. **Note:** Subscription filters in **PENDING** status can not be disabled. However, a new filter can be created instead with the **createSubscriptionFilter** method and this new filter will override the **PENDING** filter. **Parameters:** - **filter_id** (string) *required* - The unique identifier of the subscription filter to delete. Filter ID values, if configured for a subscription, will be shown in the **subscriptions.filterId** field in **getSubscription** and **getSubscription** responses. The filter ID value is also returned in the Location response header when a filter is created with **createSubscriptionFilter**. - **subscription_id** (string) *required* - The unique identifier of the subscription associated with the filter to delete. Use **getSubscriptions** to retrieve subscription IDs. ### disableSubscription #### POST /subscription/{subscription_id}/disable **Description:** This method disables a subscription, which prevents the subscription from providing notifications. To restart a subscription, call **enableSubscription**. **Parameters:** - **subscription_id** (string) *required* - The unique identifier of an enabled subscription that will be disabled. Use **getSubscriptions** to retrieve subscription IDs. ### enableSubscription #### POST /subscription/{subscription_id}/enable **Description:** This method allows applications to enable a disabled subscription. To pause (or disable) an enabled subscription, call **disableSubscription**. **Parameters:** - **subscription_id** (string) *required* - The unique identifier of a disabled subscription that will be enabled. Use **getSubscriptions** to retrieve subscription IDs. ### getSubscription #### GET /subscription/{subscription_id} **Description:** This method allows applications to retrieve subscription details for the specified subscription. Specify the subscription to retrieve using the **subscription\_id**. Use the **getSubscriptions** method to browse all subscriptions if you do not know the **subscription\_id**. Subscriptions allow applications to express interest in notifications and keep receiving the information relevant to their business. **Parameters:** - **subscription_id** (string) *required* - The unique identifier of the subscription to retrieve. Use **getSubscriptions** to retrieve subscription IDs. ### getSubscriptionFilter #### GET /subscription/{subscription_id}/filter/{filter_id} **Description:** This method allows applications to retrieve the filter details for the specified subscription filter. Specify the subscription filter to retrieve by using the **subscription\_id** and the **filter\_id** associated with the subscription filter. The **filter\_id** can be found in the response body for the **getSubscription** method, if there is a filter applied on the subscription. Filters allow applications to only be sent notifications that match a provided criteria. Notifications that do not match this criteria will not be sent to the destination. **Parameters:** - **filter_id** (string) *required* - The unique identifier of the subscription filter. Filter ID values, if configured for a subscription, will be shown in the **subscriptions.filterId** field in **getSubscription** and **getSubscription** responses. The filter ID value is also returned in the Location response header when a filter is created with **createSubscriptionFilter**. - **subscription_id** (string) *required* - The unique identifier of the subscription associated with the filter. Use **getSubscriptions** to retrieve subscription IDs. ### getSubscriptions #### GET /subscription **Description:** This method allows applications to retrieve a list of all subscriptions. The list returned is a paginated collection of subscription resources. Subscriptions allow applications to express interest in notifications and keep receiving the information relevant to their business. **Parameters:** - **continuation_token** (string) - This string value can be used to return the next page in the result set. The string to use here is returned in the next field of the current page of results. - **limit** (string) - The maximum number of subscriptions to return per page from the result set. **Min:** 10 **Max:** 100 **Default:** 20 ### testSubscription #### POST /subscription/{subscription_id}/test **Description:** This method triggers a mocked test payload that includes a notification ID, publish date, and so on. Use this method to test your subscription end-to-end. You can create the subscription in disabled mode, test it using this method, and when everything is ready, you can enable the subscription (see the **enableSubscription** method). **Note:** Use the **notificationId** to tell the difference between a test payload and a real payload. **Parameters:** - **subscription_id** (string) *required* - The unique identifier of the subscription to test. Use **getSubscriptions** to retrieve subscription IDs. ### updateSubscription #### PUT /subscription/{subscription_id} **Description:** This method allows applications to update a subscription. Subscriptions allow applications to express interest in notifications and keep receiving the information relevant to their business. **Note:** This call returns an error if an application is not authorized to subscribe to a topic. You can pause and restart a subscription. See the **disableSubscription** and **enableSubscription** methods. **Parameters:** - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. - **subscription_id** (string) *required* - The unique identifier for the subscription to update. Use **getSubscriptions** to retrieve subscription IDs. ### getTopic #### GET /topic/{topic_id} **Description:** This method allows applications to retrieve details for the specified topic. This information includes supported schema versions, formats, and other metadata for the topic. Applications can subscribe to any of the topics for a supported schema version and format, limited by the authorization scopes required to subscribe to the topic. A topic specifies the type of information to be received and the data types associated with an event. An event occurs in the eBay system, such as when a user requests deletion or revokes access for an application. An event is an instance of an event type (topic). Specify the topic to retrieve using the **topic\_id** URI parameter. **Note:** Use the [getTopics](/api-docs/commerce/notification/resources/topic/methods/getTopics) method to find a topic if you do not know the topic ID. **Parameters:** - **topic_id** (string) *required* - The unique identifier of the notification topic for which the details are retrieved. Use **getTopics** to retrieve the topic ID. ### getTopics #### GET /topic **Description:** This method returns a paginated collection of all supported topics, along with the details for the topics. This information includes supported schema versions, formats, and other metadata for the topics. Applications can subscribe to any of the topics for a supported schema version and format, limited by the authorization scopes required to subscribe to the topic. A topic specifies the type of information to be received and the data types associated with an event. An event occurs in the eBay system, such as when a user requests deletion or revokes access for an application. An event is an instance of an event type (topic). **Parameters:** - **continuation_token** (string) - This string value can be used to return the next page in the result set. The string to use here is returned in the **next** field of the current page of results. - **limit** (string) - The maximum number of notification topics to return per page from the result set. **Min:** 10 **Max:** 100 **Default:** 20 ## Error Codes The following error codes may be returned by this API: ### APPLICATION Errors #### 195026 - API_NOTIFICATION **Description:** Configuration Not Found. #### 195000 - API_NOTIFICATION **Description:** There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. ### REQUEST Errors #### 195025 - API_NOTIFICATION **Description:** Invalid or missing email. #### 195016 - API_NOTIFICATION **Description:** Invalid name. Markups or lengths greater than 64 not supported #### 195017 - API_NOTIFICATION **Description:** Invalid or missing endpoint. #### 195018 - API_NOTIFICATION **Description:** Invalid or missing destination status. Supported values:\[ENABLED,DISABLED\] #### 195019 - API_NOTIFICATION **Description:** Invalid or missing verification token for this endpoint. #### 195003 - API_NOTIFICATION **Description:** Please provide configurations required for notifications. Refer to /config #### 195020 - API_NOTIFICATION **Description:** Challenge verification failed for requested endpoint #### 195021 - API_NOTIFICATION **Description:** Destination exists for this endpoint #### 195022 - API_NOTIFICATION **Description:** Invalid or missing destination id. #### 195024 - API_NOTIFICATION **Description:** Destination is in use and cannot be deleted. #### 195004 - API_NOTIFICATION **Description:** Invalid limit. Supported ranges 10 - 100. #### 195005 - API_NOTIFICATION **Description:** Invalid continuation token. #### 195001 - API_NOTIFICATION **Description:** The specified key id is invalid. #### 195006 - API_NOTIFICATION **Description:** Invalid or missing subscription status. #### 195007 - API_NOTIFICATION **Description:** Invalid or missing destination id. #### 195008 - API_NOTIFICATION **Description:** Invalid or missing schema version. Please refer to /topic/{topic\_id} for supported schema versions. #### 195009 - API_NOTIFICATION **Description:** Specified format is not supported for the topic. #### 195010 - API_NOTIFICATION **Description:** Invalid or missing protocol #### 195027 - API_NOTIFICATION **Description:** Invalid or missing topic id. #### 195011 - API_NOTIFICATION **Description:** Not authorized for this topic. #### 195012 - API_NOTIFICATION **Description:** Subscription already exists #### 195015 - API_NOTIFICATION **Description:** The subscription cannot be enabled since the destination is not enabled. #### 195032 - API_NOTIFICATION **Description:** The specified subscription topic is not filterable. #### 195033 - API_NOTIFICATION **Description:** The specified 'filterSchema' value is invalid. #### 195028 - API_NOTIFICATION **Description:** The application is not authorized to access the specified subscription. #### 195013 - API_NOTIFICATION **Description:** The subscription id does not exist. #### 195031 - API_NOTIFICATION **Description:** The specified subscription id does not match the specified filter id. #### 195029 - API_NOTIFICATION **Description:** Invalid subscription filter id. #### 195014 - API_NOTIFICATION **Description:** The subscription cannot be enabled since the topic or payload is no longer supported. #### 195002 - API_NOTIFICATION **Description:** Invalid or missing topic id. ## Rate Limits See [API Call Limits](https://developer.ebay.com/develop/get-started/api-call-limits) on the eBay Developer Program. ## Resources ### Documentation - [eBay Developer Program](https://developer.ebay.com/) - [API Documentation](https://developer.ebay.com/develop/api/) - [SDKs and Widgets](https://developer.ebay.com/develop/sdks-and-widgets) - [Developer Community Forum](https://community.ebay.com/t5/Developer-Groups/ct-p/developergroup) ### Tools - [API Explorer](https://developer.ebay.com/my/api_test_tool) - [GraphQL Explorer](https://developer.ebay.com/my/graphql_explorer) ### Support - [Developer Support](https://developer.ebay.com/support/) - [API Status](https://developer.ebay.com/support/api-status) - [Release Notes](https://developer.ebay.com/develop/api/release_notes/) --- *Generated on 2026-07-08T04:30:24.926Z*