eBay Destination API

openapi: 3.2.0
info:
  title: eBay Notification Destination API
  description: 'The eBay Notification API enables management of the entire end-to-end eBay notification experience by allowing users to:


    Browse for supported notification topics and retrieve topic details


    Create, configure, and manage notification destination endpoints


    Configure, manage, and test notification subscriptions


    Process eBay notifications and verify the integrity of the message payload'
  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
tags:
- name: Destination
paths:
  /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
      summary: Get destinations
      x-summary-source: derived
    post:
      tags:
      - Destination
      description: 'This method allows applications to create a destination. A destination is an endpoint that receives HTTP push notifications.


        A single destination for all topics is valid, as is individual destinations for each topic.


        To update a destination, use the updateDestination call.


        The destination created will need to be referenced while creating or updating a subscription to a topic.


        Note: The destination should be created and ready to respond with the expected challengeResponse for the endpoint to be registered successfully. Refer to the Notification API overview for more information.'
      operationId: createDestination
      parameters:
      - name: Content-Type
        in: header
        description: This header indicates the format of the request body provided by the client. Its value should be set to <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
      summary: Create destination
      x-summary-source: derived
  /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
      summary: Get destination
      x-summary-source: derived
    put:
      tags:
      - Destination
      description: 'This method allows applications to update a destination.


        Note: The destination should be created and ready to respond with the expected challengeResponse for the endpoint to be registered successfully. Refer to the Notification API overview for more information.'
      operationId: updateDestination
      parameters:
      - name: 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
      summary: Update destination
      x-summary-source: derived
    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 <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
      summary: Delete destination
      x-summary-source: derived
components:
  schemas:
    DestinationRequest:
      type: object
      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:
          type: string
          description: This field sets the status for the destination endpoint as <code>ENABLED</code> or <code>DISABLED</code>.<br><br><span class="tablenote"><b>Note:</b> The <b>MARKED_DOWN</b> value is set by eBay systems and cannot be used in a create or update call by applications.</span> For implementation help, refer to <a href='https://developer.ebay.com/api-docs/commerce/notification/types/api:DestinationStatusEnum'>eBay API documentation</a>
      description: A type that contains information about the destination request.
    DeliveryConfig:
      type: object
      properties:
        endpoint:
          type: string
          description: The endpoint for this destination.
        verificationToken:
          type: string
          description: The verification token associated with this endpoint.
      description: A type that contains information about the delivery configuration.
    DestinationSearchResponse:
      type: object
      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.<br><br><b>Default:</b> 20
          format: int32
        next:
          type: string
          description: The URL to access the next set of results. This field includes a <strong>continuation_token</strong>. No <b>prev</b> field is returned, but this value is persistent during the session so that you can use it to return to the next page.<br><br>This field is not returned if fewer records than specified by the <strong>limit</strong> 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.
    Destination:
      type: object
      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:
          type: string
          description: The status for this destination.<br><br><span class="tablenote"><b>Note:</b> The <b>MARKED_DOWN</b> value is set by eBay systems and cannot be used in a create or update call by applications.</span><br><br><b>Valid values:</b><ul><li><code>ENABLED</code></li><li><code>DISABLED</code></li><li><code>MARKED_DOWN</code></li></ul> For implementation help, refer to <a href='https://developer.ebay.com/api-docs/commerce/notification/types/api:DestinationStatusEnum'>eBay API documentation</a>
      description: A type that contains information about the destination.
  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