openapi: 3.0.0 info: title: Notification API description: The eBay Notification API enables management of the entire end-to-end eBay notification experience by allowing users to: contact: name: eBay Inc, license: name: eBay API License Agreement url: https://go.developer.ebay.com/api-license-agreement version: v1.5.1 servers: - url: https://api.ebay.com{basePath} description: Production variables: basePath: default: /commerce/notification/v1 paths: /public_key/{public_key_id}: get: tags: - public_key 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 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.' operationId: getPublicKey parameters: - name: public_key_id in: path description: '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.' required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PublicKey' '400': description: Bad Request '404': description: Not Found x-response-codes: errors: '195001': domain: API_NOTIFICATION category: REQUEST description: The specified key id is invalid. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope /topic/{topic_id}: get: tags: - topic 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 method to find a topic if you do not know the topic ID. operationId: getTopic parameters: - name: topic_id in: path description: The unique identifier of the notification topic for which the details are retrieved. Use getTopics to retrieve the topic ID. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Topic' '400': description: Bad Request '404': description: Not Found x-response-codes: errors: '195002': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing topic id. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope /topic: get: tags: - 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). operationId: getTopics parameters: - name: limit in: query description: The maximum number of notification topics to return per page from the result set.

Min: 10

Max: 100

Default: 20 required: false schema: type: string - name: continuation_token in: query description: 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. required: false schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TopicSearchResponse' '400': description: Bad Request x-response-codes: errors: '195004': domain: API_NOTIFICATION category: REQUEST description: Invalid limit. Supported ranges 10 - 100. '195005': domain: API_NOTIFICATION category: REQUEST description: Invalid continuation token. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope /subscription: get: tags: - 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. operationId: getSubscriptions parameters: - name: limit in: query description: The maximum number of subscriptions to return per page from the result set.

Min: 10

Max: 100

Default: 20 required: false schema: type: string - name: continuation_token in: query description: 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. required: false schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SubscriptionSearchResponse' '400': description: Bad Request x-response-codes: errors: '195004': domain: API_NOTIFICATION category: REQUEST description: Invalid limit. Supported ranges 10 - 100. '195005': domain: API_NOTIFICATION category: REQUEST description: Invalid continuation token. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription.readonly - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription post: tags: - 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. operationId: createSubscription parameters: - name: Content-Type in: header description: This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: The create subscription request. content: application/json: schema: description: The create subscription request. $ref: '#/components/schemas/CreateSubscriptionRequest' required: false responses: '201': description: Created headers: Location: schema: type: string description: The subscription resource created. content: application/json: schema: type: object '400': description: Bad Request x-response-codes: errors: '195006': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing subscription status. '195007': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing destination id. '195008': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing schema version. Please refer to /topic/{topic_id} for supported schema versions. '195009': domain: API_NOTIFICATION category: REQUEST description: Specified format is not supported for the topic. '195010': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing protocol '195027': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing topic id. '403': description: Forbidden x-response-codes: errors: '195011': domain: API_NOTIFICATION category: REQUEST description: Not authorized for this topic. '409': description: Conflict x-response-codes: errors: '195003': domain: API_NOTIFICATION category: REQUEST description: Please provide configurations required for notifications. Refer to /config '195012': domain: API_NOTIFICATION category: REQUEST description: Subscription already exists '195015': domain: API_NOTIFICATION category: REQUEST description: The subscription cannot be enabled since the destination is not enabled. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription /subscription/{subscription_id}: get: tags: - subscription 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. operationId: getSubscription parameters: - name: subscription_id in: path description: The unique identifier of the subscription to retrieve. Use getSubscriptions to retrieve subscription IDs. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Subscription' '400': description: Bad Request '404': description: Not Found x-response-codes: errors: '195013': domain: API_NOTIFICATION category: REQUEST description: The subscription id does not exist. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription.readonly - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription put: tags: - subscription 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. operationId: updateSubscription parameters: - name: subscription_id in: path description: The unique identifier for the subscription to update. Use getSubscriptions to retrieve subscription IDs. required: true schema: type: string - name: Content-Type in: header description: This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: The create subscription request. content: application/json: schema: description: The create subscription request. $ref: '#/components/schemas/UpdateSubscriptionRequest' required: false responses: '204': description: No Content '400': description: Bad Request x-response-codes: errors: '195006': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing subscription status. '195007': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing destination id. '195008': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing schema version. Please refer to /topic/{topic_id} for supported schema versions. '195009': domain: API_NOTIFICATION category: REQUEST description: Specified format is not supported for the topic. '195010': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing protocol '404': description: Not Found x-response-codes: errors: '195013': domain: API_NOTIFICATION category: REQUEST description: The subscription id does not exist. '409': description: Conflict x-response-codes: errors: '195012': domain: API_NOTIFICATION category: REQUEST description: Subscription already exists '195014': domain: API_NOTIFICATION category: REQUEST description: The subscription cannot be enabled since the topic or payload is no longer supported. '195015': domain: API_NOTIFICATION category: REQUEST description: The subscription cannot be enabled since the destination is not enabled. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription delete: tags: - subscription description: This method allows applications to delete a subscription. Subscriptions can be deleted regardless of status. operationId: deleteSubscription parameters: - name: subscription_id in: path description: The unique identifier of the subscription to delete. Use getSubscriptions to retrieve subscription IDs. required: true schema: type: string responses: '204': description: No Content '400': description: Bad Request '404': description: Not Found x-response-codes: errors: '195013': domain: API_NOTIFICATION category: REQUEST description: ' The subscription id does not exist.' '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription /subscription/{subscription_id}/enable: post: tags: - subscription description: This method allows applications to enable a disabled subscription. To pause (or disable) an enabled subscription, call disableSubscription. operationId: enableSubscription parameters: - name: subscription_id in: path description: The unique identifier of a disabled subscription that will be enabled. Use getSubscriptions to retrieve subscription IDs. required: true schema: type: string responses: '204': description: No Content '400': description: Bad Request '404': description: Not Found x-response-codes: errors: '195013': domain: API_NOTIFICATION category: REQUEST description: The subscription id does not exist. '409': description: Conflict x-response-codes: errors: '195014': domain: API_NOTIFICATION category: REQUEST description: The subscription cannot be enabled since the topic or payload is no longer supported. '195015': domain: API_NOTIFICATION category: REQUEST description: The subscription cannot be enabled since the destination is not enabled. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription /subscription/{subscription_id}/disable: post: tags: - subscription description: This method disables a subscription, which prevents the subscription from providing notifications. To restart a subscription, call enableSubscription. operationId: disableSubscription parameters: - name: subscription_id in: path description: The unique identifier of an enabled subscription that will be disabled. Use getSubscriptions to retrieve subscription IDs. required: true schema: type: string responses: '204': description: No Content '400': description: Bad Request '404': description: Not Found x-response-codes: errors: '195013': domain: API_NOTIFICATION category: REQUEST description: The subscription id does not exist. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription /subscription/{subscription_id}/test: post: tags: - subscription 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. operationId: testSubscription parameters: - name: subscription_id in: path description: The unique identifier of the subscription to test. Use getSubscriptions to retrieve subscription IDs. required: true schema: type: string responses: '202': description: Accepted '400': description: Bad Request '404': description: Not Found x-response-codes: errors: '195013': domain: API_NOTIFICATION category: REQUEST description: ' The subscription id does not exist.' '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription /subscription/{subscription_id}/filter: post: tags: - subscription 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 method. See Creating a subscription filter for a topic 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. operationId: createSubscriptionFilter parameters: - name: subscription_id in: path description: The unique identifier of the subscription for which a filter will be created. required: true schema: type: string - name: Content-Type in: header description: This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: The create subscription filter request. content: application/json: schema: description: The create subscription filter request. $ref: '#/components/schemas/CreateSubscriptionFilterRequest' required: false responses: '201': description: Created headers: Location: schema: type: string description: The location where the subscription filter resource was created. content: application/json: schema: type: object '400': description: Bad Request x-response-codes: errors: '195032': domain: API_NOTIFICATION category: REQUEST description: The specified subscription topic is not filterable. '195033': domain: API_NOTIFICATION category: REQUEST description: The specified 'filterSchema' value is invalid. '403': description: Forbidden x-response-codes: errors: '195028': domain: API_NOTIFICATION category: REQUEST description: The application is not authorized to access the specified subscription. '404': description: Not Found x-response-codes: errors: '195013': domain: API_NOTIFICATION category: REQUEST description: The subscription id does not exist. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription /subscription/{subscription_id}/filter/{filter_id}: get: tags: - subscription 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. operationId: getSubscriptionFilter parameters: - name: subscription_id in: path description: The unique identifier of the subscription associated with the filter. Use getSubscriptions to retrieve subscription IDs. required: true schema: type: string - name: filter_id in: path description: 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. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SubscriptionFilter' '400': description: Bad Request x-response-codes: errors: '195031': domain: API_NOTIFICATION category: REQUEST description: The specified subscription id does not match the specified filter id. '403': description: Forbidden x-response-codes: errors: '195028': domain: API_NOTIFICATION category: REQUEST description: The application is not authorized to access the specified subscription. '404': description: Not Found x-response-codes: errors: '195013': domain: API_NOTIFICATION category: REQUEST description: The subscription id does not exist. '195029': domain: API_NOTIFICATION category: REQUEST description: Invalid subscription filter id. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription.readonly - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription delete: tags: - subscription 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. operationId: deleteSubscriptionFilter parameters: - name: subscription_id in: path description: The unique identifier of the subscription associated with the filter to delete. Use getSubscriptions to retrieve subscription IDs. required: true schema: type: string - name: filter_id in: path description: 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. required: true schema: type: string responses: '204': description: No Content '400': description: Bad Request x-response-codes: errors: '195031': domain: API_NOTIFICATION category: REQUEST description: The specified subscription id does not match the specified filter id. '403': description: Forbidden x-response-codes: errors: '195028': domain: API_NOTIFICATION category: REQUEST description: The application is not authorized to access the specified subscription. '404': description: Not Found x-response-codes: errors: '195013': domain: API_NOTIFICATION category: REQUEST description: The subscription id does not exist. '195029': domain: API_NOTIFICATION category: REQUEST description: Invalid subscription filter id. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope - https://api.ebay.com/oauth/api_scope/commerce.notification.subscription /destination: get: tags: - 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. operationId: getDestinations parameters: - name: limit in: query description: The maximum number of destinations to return per page from the result set.

Min: 10

Max: 100

Default: 20 required: false schema: type: string - name: continuation_token in: query description: 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. required: false schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DestinationSearchResponse' '400': description: Bad Request x-response-codes: errors: '195004': domain: API_NOTIFICATION category: REQUEST description: Invalid limit. Supported ranges 10 - 100. '195005': domain: API_NOTIFICATION category: REQUEST description: Invalid continuation token. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope post: tags: - 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 for more information. operationId: createDestination parameters: - name: Content-Type in: header description: This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: The create destination request. content: application/json: schema: description: The create destination request. $ref: '#/components/schemas/DestinationRequest' required: false responses: '201': description: Created headers: Location: schema: type: string description: The destination resource created. content: application/json: schema: type: object '400': description: Bad Request x-response-codes: errors: '195016': domain: API_NOTIFICATION category: REQUEST description: Invalid name. Markups or lengths greater than 64 not supported '195017': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing endpoint. '195018': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing destination status. Supported values:[ENABLED,DISABLED] '195019': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing verification token for this endpoint. '409': description: Conflict x-response-codes: errors: '195003': domain: API_NOTIFICATION category: REQUEST description: Please provide configurations required for notifications. Refer to /config '195020': domain: API_NOTIFICATION category: REQUEST description: Challenge verification failed for requested endpoint '195021': domain: API_NOTIFICATION category: REQUEST description: Destination exists for this endpoint '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope /destination/{destination_id}: get: tags: - destination 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. operationId: getDestination parameters: - name: destination_id in: path description: The unique identifier of the destination to retrieve. Use getDestinations to retrieve destination IDs. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Destination' '400': description: Bad Request '404': description: Not Found x-response-codes: errors: '195022': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing destination id. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope put: tags: - destination 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 for more information. operationId: updateDestination parameters: - name: destination_id in: path description: The unique identifier for the destination. required: true schema: type: string - name: Content-Type in: header description: This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: The create subscription request. content: application/json: schema: description: The create subscription request. $ref: '#/components/schemas/DestinationRequest' required: false responses: '204': description: No Content '400': description: Bad Request x-response-codes: errors: '195016': domain: API_NOTIFICATION category: REQUEST description: Invalid name. Markups or lengths greater than 64 not supported '195017': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing endpoint. '195018': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing destination status. Supported values:[ENABLED,DISABLED] '195019': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing verification token for this endpoint. '404': description: Not Found x-response-codes: errors: '195022': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing destination id. '409': description: Conflict x-response-codes: errors: '195020': domain: API_NOTIFICATION category: REQUEST description: Challenge verification failed for requested endpoint '195021': domain: API_NOTIFICATION category: REQUEST description: Destination exists for this endpoint '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope delete: tags: - destination 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. operationId: deleteDestination parameters: - name: destination_id in: path description: '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. ' required: true schema: type: string responses: '204': description: No Content '400': description: Bad Request '404': description: Not Found x-response-codes: errors: '195022': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing destination id. '409': description: Conflict x-response-codes: errors: '195024': domain: API_NOTIFICATION category: REQUEST description: Destination is in use and cannot be deleted. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope /config: get: tags: - config description: This method allows applications to retrieve a previously created configuration. operationId: getConfig responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Config' '404': description: Not Found x-response-codes: errors: '195026': domain: API_NOTIFICATION category: APPLICATION description: Configuration Not Found. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope put: tags: - 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. operationId: updateConfig parameters: - name: Content-Type in: header description: This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: The configurations for this application. content: application/json: schema: description: The configurations for this application. $ref: '#/components/schemas/Config' required: false responses: '204': description: No Content '400': description: Bad Request x-response-codes: errors: '195025': domain: API_NOTIFICATION category: REQUEST description: Invalid or missing email. '500': description: Internal Server Error x-response-codes: errors: '195000': domain: API_NOTIFICATION category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope components: schemas: Config: type: object properties: alertEmail: type: string description: This field is used to add or modify an email address that will be used for Notification API alerts associated with the application. getConfig can be used to get the email address currently being used for alerts. description: The type that defines the fields for the alertEmail field. CreateSubscriptionFilterRequest: type: object properties: filterSchema: type: object additionalProperties: type: object description: The content of a subscription filter as 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.

Note: Not all topics can have filters applied to them. Use getTopic and getTopics requests to determine if a specific topic is filterable. Filterable topics have the boolean filterable returned as true in the response.
Note: If the JSON supplied as a subscription filter specifies a field that does not exist in the notifications for a topic, or if the topic is not filterable, the filter will be rejected and become DISABLED. If it is valid, however, the filter will move from PENDING status to ENABLED status.
Initially, when the createSubscriptionFilter request has been made, if the request has a valid JSON body a 201 Created is returned. After that, the validation of the filterSchema happens. See Creating a subscription filter for a topic for additional information. CreateSubscriptionRequest: type: object properties: topicId: type: string description: The unique identifier of the notification topic to subscribe to. Use getTopics to get topic IDs. status: type: string description: Set the status of the subscription to ENABLED or DISABLED. For implementation help, refer to eBay API documentation payload: description: The payload associated with the notification topic. Use getTopics or getTopic to get the supported payload for the topic. $ref: '#/components/schemas/SubscriptionPayloadDetail' destinationId: type: string description: The unique identifier of the destination endpoint that will receive notifications associated with this subscription. Use the getDestinations method to retrieve destination IDs. description: This type contains information about a subscription request. DeliveryConfig: type: object properties: endpoint: type: string description: The endpoint for this destination. verificationToken: type: string description: The verification token associated with this endpoint. description: A type that contains information about the delivery configuration. Destination: type: object properties: destinationId: type: string description: The unique identifier for the destination. name: type: string description: The name associated with this destination. status: type: string description: The status for this destination.

Note: The MARKED_DOWN value is set by eBay systems and cannot be used in a create or update call by applications.

Valid values: For implementation help, refer to eBay API documentation deliveryConfig: description: The configuration associated with this destination. $ref: '#/components/schemas/DeliveryConfig' description: A type that contains information about the destination. DestinationRequest: type: object properties: name: type: string description: The seller-specified name for the destination endpoint. status: type: string description: This field sets the status for the destination endpoint as ENABLED or DISABLED.

Note: The MARKED_DOWN value is set by eBay systems and cannot be used in a create or update call by applications. For implementation help, refer to eBay API documentation deliveryConfig: description: This container is used to specify the destination endpoint and verification token associated with this endpoint. $ref: '#/components/schemas/DeliveryConfig' description: A type that contains information about the destination request. DestinationSearchResponse: type: object properties: total: type: integer description: The total number of matches for the search criteria. format: int32 href: type: string description: The path to the call URI that produced the current page of results. next: type: string description: The URL to access the next set of results. This field includes a continuation_token. No prev field is returned, but this value is persistent during the session so that you can use it to return to the next page.

This field is not returned if fewer records than specified by the limit field are returned. limit: type: integer description: The number of records to show in the current response.

Default: 20 format: int32 destinations: type: array description: An array that contains the destination details. items: $ref: '#/components/schemas/Destination' description: A type that contains information about the destination search response. Error: type: object properties: category: type: string description: Identifies the type of erro. domain: type: string description: Name for the primary system where the error occurred. This is relevant for application errors. errorId: type: integer description: A unique number to identify the error. format: int32 inputRefIds: type: array description: An array of request elements most closely associated to the error. items: type: string longMessage: type: string description: A more detailed explanation of the error. message: type: string description: Information on how to correct the problem, in the end user's terms and language where applicable. outputRefIds: type: array description: An array of request elements most closely associated to the error. items: type: string parameters: type: array description: An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned. items: $ref: '#/components/schemas/ErrorParameter' subdomain: type: string description: 'Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc.' description: This type defines the fields that can be returned in an error. ErrorParameter: type: object properties: name: type: string description: The object of the error. value: type: string description: The value of the object. PayloadDetail: type: object properties: schemaVersion: type: string description: The supported schema version. format: type: array description: The supported format. Presently, JSON is the only supported format. items: type: string description: ' For implementation help, refer to eBay API documentation' deliveryProtocol: type: string description: The supported delivery protocols. For implementation help, refer to eBay API documentation deprecated: type: boolean description: A deprecation indicator. description: A type that describes the details about a topic's payload. PublicKey: type: object properties: algorithm: type: string description: The algorithm associated with the public key that is returned, such as Elliptic Curve Digital Signature Algorithm (ECDSA). digest: type: string description: The digest associated with the public key that is returned, such as Secure Hash Algorithm 1 (SHA1). key: type: string description: The public key that is returned for the specified key ID.

This value is used to validate the eBay push notification message payload. description: A type that defines the public key for a unique key ID. Subscription: type: object properties: subscriptionId: type: string description: The unique identifier for the subscription. topicId: type: string description: The unique identifier for the topic associated with this subscription. status: type: string description: The status of this subscription. For implementation help, refer to eBay API documentation creationDate: type: string description: The creation date for this subscription. payload: description: The payload associated with this subscription. $ref: '#/components/schemas/SubscriptionPayloadDetail' destinationId: type: string description: The unique identifier for the destination associated with this subscription. filterId: type: string description: The unique identifier for the filter associated with this subscription. description: A type that describes the subscription. SubscriptionFilter: type: object properties: subscriptionId: type: string description: The unique identifier for the subscription. filterId: type: string description: The unique identifier for this subscription filter. filterSchema: type: object additionalProperties: type: object description: The content of this subscription filter as 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. filterStatus: type: string description: The status of this subscription filter. For implementation help, refer to eBay API documentation creationDate: type: string description: The creation date for this subscription filter. SubscriptionPayloadDetail: type: object properties: format: type: string description: The supported data format of the payload.

Note: JSON is currently the only supported format for all notification topics. For implementation help, refer to eBay API documentation schemaVersion: type: string description: The supported schema version for the notification topic. See the supportedPayloads.schemaVersion field for the topic in getTopics or getTopic response. deliveryProtocol: type: string description: The supported delivery protocol of the notification topic.

Note: HTTPS is currently the only supported delivery protocol of all notification topics. For implementation help, refer to eBay API documentation description: A type that describes the details of the subscription payload. SubscriptionSearchResponse: type: object properties: total: type: integer description: The total number of matches for the search criteria. format: int32 href: type: string description: The path to the call URI that produced the current page of results. next: type: string description: The URL to access the next set of results. This field includes a continuation_token. No prev field is returned, but this value is persistent during the session so that you can use it to return to the next page.

This field is not returned if fewer records than specified by the limit field are returned. limit: type: integer description: The value of the limit parameter submitted in the request, which is the maximum number of items to return per page, from the result set. A result set is the complete set of results returned by the method.

Note: Though this parameter is not required to be submitted in the request, the parameter defaults to 20 if omitted.

Default: 20 format: int32 subscriptions: type: array description: The subscriptions that match the search criteria. items: $ref: '#/components/schemas/Subscription' description: A type that describes the details of the subscription search response. Topic: type: object properties: topicId: type: string description: The unique identifier for the topic. description: type: string description: The description of the topic. authorizationScopes: type: array description: The authorization scopes required to subscribe to this topic. items: type: string status: type: string description: The status of this topic. For implementation help, refer to eBay API documentation context: type: string description: The business context associated with this topic. For implementation help, refer to eBay API documentation scope: type: string description: The scope of this topic. For implementation help, refer to eBay API documentation supportedPayloads: type: array description: The supported payloads for this topic. items: $ref: '#/components/schemas/PayloadDetail' filterable: type: boolean description: The indicator of whether this topic is filterable or not. description: A type that describes the details of the topic. TopicSearchResponse: type: object properties: total: type: integer description: The total number of matches for the search criteria. format: int32 href: type: string description: The path to the call URI that produced the current page of results. next: type: string description: The URL to access the next set of results. This field includes a continuation_token. No prev field is returned, but this value is persistent during the session so that you can use it to return to the next page.

This field is not returned if fewer records than specified by the limit field are returned. limit: type: integer description: The value of the limit parameter submitted in the request, which is the maximum number of items to return per page, from the result set. A result set is the complete set of results returned by the method.

Note: Though this parameter is not required to be submitted in the request, the parameter defaults to 20 if omitted. format: int32 topics: type: array description: An array of topics that match the specified criteria. items: $ref: '#/components/schemas/Topic' description: A type that describes the details of the topic search response. UpdateSubscriptionRequest: type: object properties: status: type: string description: Set the status of the subscription being updated to ENABLED or DISABLED. For implementation help, refer to eBay API documentation payload: description: The payload associated with this subscription. $ref: '#/components/schemas/SubscriptionPayloadDetail' destinationId: type: string description: The unique identifier of the destination endpoint that will receive notifications associated with this subscription. Use getDestinations to retrieve destination IDs. description: A type that describes the details of the update subscription request. securitySchemes: api_auth: type: oauth2 description: The security definitions for this API. Please check individual operations for applicable scopes. flows: clientCredentials: tokenUrl: https://api.ebay.com/identity/v1/oauth2/token scopes: https://api.ebay.com/oauth/api_scope: View public data from eBay authorizationCode: authorizationUrl: https://auth.ebay.com/oauth2/authorize tokenUrl: https://api.ebay.com/identity/v1/oauth2/token scopes: https://api.ebay.com/oauth/api_scope/commerce.notification.subscription.readonly: View your event notification subscriptions https://api.ebay.com/oauth/api_scope/commerce.notification.subscription: View and manage your event notification subscriptions