eBay Destination API

openapi: 3.0.0
info:
  title: eBay Account Advertising_eligibility Destination API
  description: The <b>Account API</b> gives sellers the ability to configure their eBay seller accounts, including the seller's policies (eBay business policies and seller-defined custom policies), opt in and out of eBay seller programs, configure sales tax tables, and get account information.  <br><br>For details on the availability of the methods in this API, see <a href="/api-docs/sell/account/overview.html#requirements">Account API requirements and restrictions</a>.
  contact:
    name: eBay Inc,
  license:
    name: eBay API License Agreement
    url: https://go.developer.ebay.com/api-license-agreement
  version: v1.9.2
servers:
- url: https://api.ebay.com{basePath}
  description: Production
  variables:
    basePath:
      default: /sell/account/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
    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
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.
    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.
    DeliveryConfig:
      type: object
      properties:
        endpoint:
          type: string
          description: The endpoint for this destination.
        verificationToken:
          type: string
          description: The verification token associated with this endpoint.
      description: A type that contains information about the delivery configuration.
    Destination:
      type: object
      properties:
        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:
        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/sell.account.readonly: View your account settings
            https://api.ebay.com/oauth/api_scope/sell.account: View and manage your account settings