{ "openapi": "3.1.0", "info": { "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.", "contact": { "name": "eBay Inc," }, "license": { "name": "eBay API License Agreement", "url": "https://developer.ebay.com/join/api-license-agreement" }, "version": "v1.6.7" }, "servers": [ { "url": "https://api.ebay.com{basePath}", "description": "Production", "variables": { "basePath": { "default": "/commerce/notification/v1" } } } ], "security": [ {} ], "paths": { "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195026": { "domain": "API_NOTIFICATION", "category": "APPLICATION", "description": "Configuration Not Found." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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.", "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195025": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": "Invalid or missing email." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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": { "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": "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" } }, { "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" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationSearchResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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. See the Communications Guide 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.", "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195022": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": "Invalid or missing destination id." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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.", "operationId": "updateDestination", "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.", "required": true, "schema": { "type": "string" } }, { "name": "destination_id", "in": "path", "description": "The unique identifier for the destination.", "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195022": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": "Invalid or missing destination id." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195022": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": "Invalid or missing destination id." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195024": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": "Destination is in use and cannot be deleted." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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" ] } ] } }, "/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 Communications Guide.", "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195001": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": "The specified key id is invalid." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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": "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" } }, { "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" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionSearchResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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.", "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195011": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": "Not authorized for this topic." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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.

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": "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.", "required": true, "schema": { "type": "string" } }, { "name": "subscription_id", "in": "path", "description": "The unique identifier of the subscription for which a filter will be created.", "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195013": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": "The subscription id does not exist." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195013": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": "The subscription id does not exist." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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 enableSubscriptionmethods.", "operationId": "updateSubscription", "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.", "required": true, "schema": { "type": "string" } }, { "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" } } ], "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195013": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": "The subscription id does not exist." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195013": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": " The subscription id does not exist." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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": "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" } }, { "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" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionFilter" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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": "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" } }, { "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" } } ], "responses": { "204": { "description": "No Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195013": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": "The subscription id does not exist." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195013": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": "The subscription id does not exist." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195013": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": " The subscription id does not exist." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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" ] } ] } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "195002": { "domain": "API_NOTIFICATION", "category": "REQUEST", "description": "Invalid or missing topic id." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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": "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" } }, { "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" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicSearchResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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", "required": [ "alertEmail" ], "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." }, "ContextEnum": { "type": "object", "description": "An enumerated type that represents the business context of a notification. | **BUY**: This value represents notifications related to buyer-side use cases (buying flows and behavior). - **SELL**: This value represents notifications related to seller-side use cases (listing, selling, and order handling). - **COMMERCE**: This value represents notifications that apply to broader commerce flows spanning buy/sell (e.g., account or marketplace–level events). - **DEVELOPER**: This value represents notifications aimed at developer-level concerns or tooling.", "enum": [ "BUY", "SELL", "COMMERCE", "DEVELOPER" ] }, "CreateSubscriptionFilterRequest": { "type": "object", "description": "This type defines the request fields for the createSubscriptionFilter method.", "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." } } }, "CreateSubscriptionRequest": { "type": "object", "properties": { "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." }, "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" }, "status": { "description": "Set the status of the subscription to ENABLED or DISABLED.", "$ref": "#/components/schemas/SubscriptionStatusEnum" }, "topicId": { "type": "string", "description": "The unique identifier of the notification topic to subscribe to. Use getTopics to get topic IDs." } }, "description": "This type contains information about a subscription request." }, "DeliveryConfig": { "type": "object", "required": [ "endpoint", "verificationToken" ], "properties": { "endpoint": { "type": "string", "description": "The endpoint for this destination.

Note: The provided endpoint URL should use the HTTPS protocol, and it should not contain an internal IP address or localhost in its path." }, "verificationToken": { "type": "string", "description": "The verification token associated with this endpoint.

Note: The provided verification token must be between 32 and 80 characters. Allowed characters include alphanumeric characters, underscores (_), and hyphens (-); no other characters are allowed." } }, "description": "A type that contains information about the delivery configuration." }, "Destination": { "type": "object", "required": [ "deliveryConfig", "destinationId", "status" ], "properties": { "deliveryConfig": { "description": "The configuration associated with this destination.", "$ref": "#/components/schemas/DeliveryConfig" }, "destinationId": { "type": "string", "description": "The unique identifier for the destination." }, "name": { "type": "string", "description": "The name associated with this destination." }, "status": { "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:", "$ref": "#/components/schemas/DestinationStatusEnum" } }, "description": "A type that contains information about the destination." }, "DestinationRequest": { "type": "object", "required": [ "deliveryConfig", "status" ], "properties": { "deliveryConfig": { "description": "This container is used to specify the destination endpoint and verification token associated with this endpoint.", "$ref": "#/components/schemas/DeliveryConfig" }, "name": { "type": "string", "description": "The seller-specified name for the destination endpoint." }, "status": { "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.", "$ref": "#/components/schemas/DestinationStatusEnum" } }, "description": "A type that contains information about the destination request." }, "DestinationSearchResponse": { "type": "object", "required": [ "href" ], "properties": { "destinations": { "type": "array", "description": "An array that contains the destination details.", "items": { "$ref": "#/components/schemas/Destination" } }, "href": { "type": "string", "description": "The path to the call URI that produced the current page of results." }, "limit": { "type": "integer", "description": "The number of records to show in the current response.

Default: 20", "format": "int32" }, "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." }, "total": { "type": "integer", "description": "The total number of matches for the search criteria.", "format": "int32" } }, "description": "A type that contains information about the destination search response." }, "DestinationStatusEnum": { "type": "object", "description": "An enumerated type that describes the current status of a notification destination endpoint. | - **ENABLED**: This enumeration value indicates the destination is active and can receive notifications. - **DISABLED**: This enumeration value indicates the destination exists but is turned off and will not receive notifications. - **MARKED_DOWN**: This enumeration value indicates the destination has been automatically marked down by eBay systems (e.g., due to failures) and this value cannot be set via create/update calls.", "enum": [ "ENABLED", "DISABLED", "MARKED_DOWN" ] }, "Error": { "type": "object", "properties": { "category": { "type": "string", "description": "Identifies the type of error." }, "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", "description": "This type defines the name and value of the error.", "properties": { "name": { "type": "string", "description": "The object of the error." }, "value": { "type": "string", "description": "The value of the object." } } }, "FormatTypeEnum": { "type": "object", "description": "An enumerated type that describes the format of the subscription's payload. | - **JSON**: Presently, only JSON is supported.", "enum": [ "JSON" ] }, "PayloadDetail": { "type": "object", "required": [ "deliveryProtocol", "deprecated", "format" ], "properties": { "deliveryProtocol": { "description": "The supported delivery protocols.", "$ref": "#/components/schemas/ProtocolEnum" }, "deprecated": { "type": "boolean", "description": "A deprecation indicator." }, "format": { "type": "array", "description": "The supported format. Presently, JSON is the only supported format.", "items": { "$ref": "#/components/schemas/FormatTypeEnum" } }, "schemaVersion": { "type": "string", "description": "The supported schema version." } }, "description": "A type that describes the details about a topic's payload." }, "ProtocolEnum": { "type": "object", "description": "An enumerated type that defines the allowed transport protocol for payload delivery. | - **HTTPS**: Presently, HTTPS is the only supported format.", "enum": [ "HTTPS" ] }, "PublicKey": { "type": "object", "required": [ "algorithm", "digest", "key" ], "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." }, "ScopeEnum": { "type": "object", "description": "An enumerated type that indicates whether a notification topic is scoped to an application or to an individual user. | - **APPLICATION**: This enumeration value indicates the topic is subscribed to and managed at the application level. - **USER**: This enumeration value indicates the topic is subscribed to and managed per user account.", "enum": [ "APPLICATION", "USER" ] }, "StatusEnum": { "type": "object", "description": "An enumerated type that represents the status of the notification topic. | - **ENABLED**: This enumeration value indicates the topic is active and can be subscribed to and used. - **DISABLED**: This enumeration value indicates the topic is turned off and not available for active use. - **DEPRECATED**: This enumeration value indicates the topic is deprecated and will be removed or replaced.", "enum": [ "ENABLED", "DISABLED", "DEPRECATED" ] }, "Subscription": { "type": "object", "properties": { "creationDate": { "type": "string", "description": "The creation date for this subscription." }, "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." }, "payload": { "description": "The payload associated with this subscription.", "$ref": "#/components/schemas/SubscriptionPayloadDetail" }, "status": { "description": "The status of this subscription.", "$ref": "#/components/schemas/SubscriptionStatusEnum" }, "subscriptionId": { "type": "string", "description": "The unique identifier for the subscription." }, "topicId": { "type": "string", "description": "The unique identifier for the topic associated with this subscription." } }, "description": "A type that describes the subscription." }, "SubscriptionFilter": { "description": "This type defines filter details for the specified subscription filter.", "type": "object", "properties": { "creationDate": { "type": "string", "description": "The creation date for this subscription filter." }, "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": { "description": "The status of this subscription filter.", "$ref": "#/components/schemas/SubscriptionFilterStatus" }, "subscriptionId": { "type": "string", "description": "The unique identifier for the subscription." } } }, "SubscriptionFilterStatus": { "type": "object", "description": "An enumerated type that indicates the current status of the subscription filter. | - **DISABLED**: The subscription filter exists but is currently turned off; it does not affect which notifications are sent. - **ENABLED**: The subscription filter is active and is being applied to determine which notifications are delivered. - **PENDING**: The subscription filter has been created but is not yet active (e.g., awaiting processing/activation).", "enum": [ "DISABLED", "ENABLED", "PENDING" ] }, "SubscriptionPayloadDetail": { "type": "object", "properties": { "deliveryProtocol": { "description": "The supported delivery protocol of the notification topic.

Note: HTTPS is currently the only supported delivery protocol of all notification topics. ", "$ref": "#/components/schemas/ProtocolEnum" }, "format": { "description": "The supported data format of the payload.

Note: JSON is currently the only supported format for all notification topics.", "$ref": "#/components/schemas/FormatTypeEnum" }, "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." } }, "description": "A type that describes the details of the subscription payload." }, "SubscriptionSearchResponse": { "type": "object", "required": [ "href", "limit", "total" ], "properties": { "href": { "type": "string", "description": "The path to the call URI that produced the current page of results." }, "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" }, "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." }, "subscriptions": { "type": "array", "description": "The subscriptions that match the search criteria.", "items": { "$ref": "#/components/schemas/Subscription" } }, "total": { "type": "integer", "description": "The total number of matches for the search criteria.", "format": "int32" } }, "description": "A type that describes the details of the subscription search response." }, "SubscriptionStatusEnum": { "type": "object", "description": "An enumerated type that describes whether a subscription is active. | - **ENABLED**: The subscription is active and eBay will send notifications for that subscription. - **DISABLED**: The subscription is turned off and no notifications will be sent for that subscription.", "enum": [ "ENABLED", "DISABLED" ] }, "SubscriptionTestResponse": { "type": "object", "properties": { "notificationId": { "type": "string", "description": "The unique identifier for the notification for this test message." } }, "description": "A type that describes the response of the test." }, "Topic": { "type": "object", "required": [ "context", "description", "filterable", "scope", "status", "topicId" ], "properties": { "authorizationScopes": { "type": "array", "description": "The authorization scopes required to subscribe to this topic.", "items": { "type": "string" } }, "context": { "description": "The business context associated with this topic.", "$ref": "#/components/schemas/ContextEnum" }, "description": { "type": "string", "description": "The description of the topic." }, "filterable": { "type": "boolean", "description": "The indicator of whether this topic is filterable or not." }, "scope": { "description": "The scope of this topic.", "$ref": "#/components/schemas/ScopeEnum" }, "status": { "description": "The status of this topic.", "$ref": "#/components/schemas/StatusEnum" }, "supportedPayloads": { "type": "array", "description": "The supported payloads for this topic.", "items": { "$ref": "#/components/schemas/PayloadDetail" } }, "topicId": { "type": "string", "description": "The unique identifier for the topic." } }, "description": "A type that describes the details of the topic." }, "TopicSearchResponse": { "type": "object", "required": [ "href", "limit", "total" ], "properties": { "href": { "type": "string", "description": "The path to the call URI that produced the current page of results." }, "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" }, "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." }, "topics": { "type": "array", "description": "An array of topics that match the specified criteria.", "items": { "$ref": "#/components/schemas/Topic" } }, "total": { "type": "integer", "description": "The total number of matches for the search criteria.", "format": "int32" } }, "description": "A type that describes the details of the topic search response." }, "UpdateSubscriptionRequest": { "type": "object", "properties": { "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." }, "payload": { "description": "The payload associated with this subscription.", "$ref": "#/components/schemas/SubscriptionPayloadDetail" }, "status": { "description": "Set the status of the subscription being updated to ENABLED or DISABLED.", "$ref": "#/components/schemas/SubscriptionStatusEnum" } }, "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" } } } }, "bearerAuth": { "type": "http", "scheme": "bearer" } } } }