eBay
eBay Notification API

The eBay Notification API manages destinations and subscriptions for the event-driven notifications eBay publishes to integrators, including marketplace account deletion, item availability, item price, campaign budget status, and authorization revocation events.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  title: eBay Notification API
  description: The eBay Notification API enables management of the entire end-to-end eBay notification experience by allowing users to:<ul><li>Browse for supported notification topics and retrieve topic details</li><li>Create, configure, and manage notification destination endpoints</li><li>Configure, manage, and test notification subscriptions</li><li>Process eBay notifications and verify the integrity of the message payload</li></ul>
  contact:
    name: eBay Inc,
  license:
    name: eBay API License Agreement
    url: https://developer.ebay.com/join/api-license-agreement
  version: v1.5.1
servers:
  - url: https://api.ebay.com{basePath}
    description: Production
    variables:
      basePath:
        default: /commerce/notification/v1
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
          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 <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
          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
  /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 <b>next</b> 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.<br><br><b>Min:</b> 10<br><br><b>Max:</b> 100<br><br><b>Default:</b> 20
          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.<br><br>A single destination for all topics is valid, as is individual destinations for each topic.<br><br>To update a destination, use the <strong>updateDestination</strong> call.<br><br>The destination created will need to be referenced while creating or updating a subscription to a topic.<br><br><span class="tablenote"><b>Note:</b> The destination should be created and ready to respond with the expected <b>challengeResponse</b> for the endpoint to be registered successfully. Refer to the <a href="/api-docs/commerce/notification/overview.html">Notification API overview</a> for more information.</span>
      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 <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
          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 <b>getDestinations</b> 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.<br><br><span class="tablenote"><b>Note:</b> The destination should be created and ready to respond with the expected <b>challengeResponse</b> for the endpoint to be registered successfully. Refer to the <a href="/api-docs/commerce/notification/overview.html">Notification API overview</a> for more information.</span>
      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 <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
          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
        '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.<br><br>The same destination ID can be used by many destinations.<br><br>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 <b>getDestination</b> or <b>getDestinations</b> 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
  /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.<br><br>The public key ID, which is a required request parameter for this method, is retrieved from the Base64-encoded <b>X-EBAY-SIGNATURE</b> header that is included in the eBay notification.<br><br><div class="msgbox_important"><p class="msgbox_importantInDiv" data-mc-autonum="&lt;b&gt;&lt;span style=&quot;color: #dd1e31;&quot; class=&quot;mcFormatColor&quot;&gt;Important! &lt;/span&gt;&lt;/b&gt;"><span class="autonumber"><span><b><span style="color: #dd1e31;" class="mcFormatColor">Important!</span></b></span></span> 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 <a href="/develop/apis/api-call-limits" target="_blank">API call limits</a> if a large number of notification requests is received.</p></div><br><span class="tablenote"><b>Note:</b> For more details about how to process eBay push notifications and validate notification message payloads, see the <a href="/api-docs/commerce/notification/overview.html">Notification API overview</a>.</span>'
      operationId: getPublicKey
      parameters:
        - name: public_key_id
          in: path
          description: 'The unique key ID that is used to retrieve the public key.<br><br><span class="tablenote"><b>Note: </b>This is retrieved from the <b>X-EBAY-SIGNATURE</b> header that is included with the push notification.</span>'
          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
  /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.<br><br>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.<br><br><b>Min:</b> 10<br><br><b>Max:</b> 100<br><br><b>Default:</b> 20
          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.<br><br>Each application and topic-schema pairing to a subscription should have a 1:1 cardinality.<br><br>You can create the subscription in disabled mode, test it (see the <b>test</b> method), and when everything is ready, you can enable the subscription (see the <b>enableSubscription</b> method).<br><br><span class="tablenote"><b>Note:</b> 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.</span>
      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 <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
          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}/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.<br><br>The <strong>filterSchema</strong> value must be a valid <a href="https://json-schema.org " target="_blank">JSON Schema Core document</a> (version 2020-12 or later). The <strong>filterSchema</strong> 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 <code>$schema</code> and <code>$id</code> definitions.<br><br>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 <b>201&nbsp;Created</b>. Newly created filters are in <code>PENDING</code> status until they are reviewed. If a filter is valid, it will move from <code>PENDING</code> status to <code>ENABLED</code> status. You can find the status of a filter using the <a href="/api-docs/commerce/notification/resources/subscription/methods/getSubscriptionFilter">getSubscriptionFilter</a> method. See <a href="/api-docs/commerce/notification/overview.html#create-filter" target="_blank">Creating a subscription filter for a topic</a> for additional information.<br><br><span class="tablenote"><b>Note:</b> Only one filter can be in <strong>ENABLED</strong> (which means active) status on a subscription at a time. If an <strong>ENABLED</strong> filter is overwritten by a new call to <strong>CREATE</strong> a filter for the subscription, it stays in <strong>ENABLED</strong> status until the new <strong>PENDING</strong> filter becomes the <strong>ENABLED</strong> filter, and the existing filter then becomes <strong>DISABLED</strong>.</span>
      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 <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
          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
          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}:
    get:
      tags:
        - Subscription
      description: This method allows applications to retrieve subscription details for the specified subscription.<br><br>Specify the subscription to retrieve using the <strong>subscription_id</strong>. Use the <strong>getSubscriptions</strong> method to browse all subscriptions if you do not know the <strong>subscription_id</strong>.<br><br>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 <b>getSubscriptions</b> 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 informati

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ebay/refs/heads/main/openapi/ebay-notification-openapi-original.yml
eBay Notification API

Documentation

Specifications

Other Resources

OpenAPI Specification
