topsort-api-v1.yml

openapi: 3.0.1
info:
  title: Topsort Endpoints v1 API Reference
  contact:
    email: wicha@topsort.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  x-logo:
    url: https://assets.topsort.com/Topsort_logo_icon_dark.svg
    backgroundColor: '#fff'
    altText: Topsort
  version: 1.0.1

servers:
  - url: https://api.topsort.com/v1
    description: Auctions v1 path

tags:
  - name: Auctions
    description: An auction determines which products should be promoted based on the vendors' bids.
  - name: Events
    description: Significant consumer interactions on the e-commerce site.
  - name: Models
    x-displayName: All Models
    description: |
      ## Auction
      <SchemaDefinition schemaRef="#/components/schemas/Auction" />

      ## Auction Request (Sponsored Listings)
      <SchemaDefinition schemaRef="#/components/schemas/AuctionRequest" />

      ## Click Event
      <SchemaDefinition schemaRef="#/components/schemas/ClickEvent" />

      ## Click Response
      <SchemaDefinition schemaRef="#/components/schemas/ClickResponse" />

      ## Error
      <SchemaDefinition schemaRef="#/components/schemas/Error" />

      ## Geotargeting
      <SchemaDefinition schemaRef="#/components/schemas/GeoTargeting" />

      ## Impression
      <SchemaDefinition schemaRef="#/components/schemas/Impression" />

      ## Impression Event
      <SchemaDefinition schemaRef="#/components/schemas/ImpressionEvent" />

      ## Impressions Response
      <SchemaDefinition schemaRef="#/components/schemas/ImpressionsResponse" />

      ## Placement
      <SchemaDefinition schemaRef="#/components/schemas/Placement" />

      ## Product
      <SchemaDefinition schemaRef="#/components/schemas/Product" />

      ## Purchase Event
      <SchemaDefinition schemaRef="#/components/schemas/PurchaseEvent" />

      ## Purchase Item
      <SchemaDefinition schemaRef="#/components/schemas/PurchaseItem" />

      ## Purchase Response
      <SchemaDefinition schemaRef="#/components/schemas/PurchaseResponse" />

      ## Session
      <SchemaDefinition schemaRef="#/components/schemas/Session" />

      ## Winner
      <SchemaDefinition schemaRef="#/components/schemas/Winner" />

security:
  - BearerAuth: []

paths:
  /auctions:
    post:
      deprecated: true
      tags:
        - Auctions
      summary: Creates a new auction
      operationId: createAuction
      requestBody:
        description: >
          The information describing what will be auctioned.
          Topsort will run an auction for each slot type, for which products' bids will compete against each other.
          The products that will participate are included in the request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuctionRequest'
        required: true
      responses:
        201:
          description:
            "The auction results. The list of Winner objects will contain at most slots entries.
            It may contain fewer or no entries at all if there aren't enough products with usable bids.
            Bids become unusable if their campaign budget is exhausted, the bid is disqualified to preserve spend pacing, etc."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Auction'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'

  /events:
    post:
      deprecated: true
      tags:
        - Events
      summary: Report an event
      operationId: reportEvent
      requestBody:
        description: 'Use the `/events` endpoint to notify Topsort about significant consumer interactions on the e-commerce site: impressions -- product links become visible to the consumer; clicks -- the consumer clicks on a product link; and purchases -- the consumer buys some products.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
        required: true
      responses:
        200:
          description:
            'An object containing the markeplace ID for the event and the Topsort ID for the same event.
            Logging this can facilitate debugging.
            The field name for the TopsortID will be "impressionID", "clickId" or "purchaseId"
            depending on the event in the request.'
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ImpressionsResponse'
                  - $ref: '#/components/schemas/ClickResponse'
                  - $ref: '#/components/schemas/PurchaseResponse'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        400:
          $ref: '#/components/responses/BadRequest'

components:
  responses:
    UnauthorizedError:
      description: Access token is missing or invalid.
    BadRequest:
      description: HTTP status codes as registered with IANA.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    AuctionRequest:
      type: object
      required:
        - slots
        - products
      properties:
        slots:
          $ref: '#/components/schemas/Slots'
        products:
          type: array
          description: An array of objects, each describing a product that should participate in the auction.
          items:
            $ref: '#/components/schemas/Product'
          minItems: 1
        session:
          $ref: '#/components/schemas/Session'
        geoTargeting:
          $ref: '#/components/schemas/GeoTargeting'
      example:
        slots:
          listings: 2
        products:
          - productId: p_SA0238
            quality: 0.75
          - productId: p_SA0250
            quality: 0.9
          - productId: p_SA0259
            quality: 0.7

    Auction:
      type: object
      properties:
        slots:
          type: object
          properties:
            listings:
              type: object
              properties:
                auctionId:
                  type: string
                  description: Topsort assigned ID for the auction. Should be used in reporting impressions, clicks and purchases.
                  example: AKFU78
                winners:
                  type: array
                  items:
                    $ref: '#/components/schemas/Winner'
                  description:
                    'Array of winner objects in order from highest to lowest bid.
                    May be empty if there were no qualifying bids.'

    GeoTargeting:
      type: object
      description: An object describing geographical information associated with this auction.
      required:
        - location
      properties:
        location:
          description: The location this auction is being run for.
          type: string
          minLength: 1

    Winner:
      type: object
      required:
        - rank
        - productId
      properties:
        rank:
          type: integer
          description: >
            Where the product's bid ranked in the auction.
            One-based, so the product with rank 1 won the auction.
            In an auction response, the winners array is sorted so rank will match the entry's index.
          minimum: 1
        productId:
          type: string
          description: The marketplace's ID for the product. It will match the ID for a product in the request's products array.
          example: pSA0238
        winnerType:
          type: string
          description: The type of the winning bid, depending on the campaign. It can be product or vendor.
          enum:
            - product
            - vendor
        winnerId:
          type: string
          description: The marketplace's ID of the winnning item, depending on the campaign.
          example: b_Mfk15
        resolvedBidId:
          type: string
          description: An opaque topsort ID to be used when this item is interacted with.
          example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=

    Product:
      required:
        - productId
      type: object
      properties:
        productId:
          type: string
          format: string
          example: p_SA0238
          minLength: 1
        quality:
          type: number
          minimum: 0
          maximum: 1
          exclusiveMinimum: true
          example: 0.75
          format: double
      xml:
        name: Product

    Session:
      description: The Session object allows correlating user activity during a session whether or not they are actually logged in.
      required:
        - sessionId
      type: object
      properties:
        sessionId:
          description: >
            Long-lived token identifying the customer interacting with the marketplace.

            If your users are always logged in you may use a hash of your customer ID.
            If your users may interact with your app or site while logged out we recommend generating a random identifier (UUIDv4) on first load and store it on local storage (cookie, local storage, etc) and let it live for at least a year.
          type: string
          minLength: 1
          example: ebeaf802-6d0a-41a3-ae59-661887c4f6cb
        # consumerId:
        #   description: >
        #     Optional ID identifying the user, this field is required in case your marketplace wants to do cross-device attribution.
        #
        #     Instead of sending us the exact same user ID you are storing in your systems we recommend you to send us a hash of the user ID (SHA1, SHA512, etc).
        #     This field is needed for cross-device attribution.
        #   type: string
        #   example: cid_86hkz2p3171joer80pdkltu7n

    Placement:
      type: object
      required:
        - page
      properties:
        page:
          type: string
          description: A marketplace assigned name for a page.
          minLength: 1
          example: search_results
        location:
          type: string
          description: A marketplace defined name for a page part.
          minLength: 1
          example: position_1

    ClickEvent:
      description: ClickEvents are sent to Topsort when the consumer has clicked on an impression. Topsort charges the vendor and pays the marketplace for clicks on impressions in promoted placements on the e-commerce site.
      type: object
      required:
        - eventType
        - session
        - placement
      properties:
        eventType:
          type: string
          description: Discriminator for the type of event.
          enum:
            - Click
        session:
          $ref: '#/components/schemas/Session'
        placement:
          $ref: '#/components/schemas/Placement'
        productId:
          type: string
          description: The product that was clicked.
          minLength: 1
          example: p_SA0238
        auctionId:
          type: string
          description: Required for promoted products. Must be the ID for the auction the product won.
          minLength: 1
          example: AKFU78
        id:
          type: string
          description: The marketplace's unique ID for the click.
          minLength: 1
          example: 234f678-f90c
        occurredAt:
          type: string
          format: date-time
          description: RFC3339 formatted timestamp including UTC offset
          example: '2009-01-01T12:59:59-05:00'
        resolvedBidId:
          type: string
          minLength: 1
          example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
      example:
        eventType: Click
        session:
          sessionId: ebeaf802-6d0a-41a3-ae59-661887c4f6cb
        placement:
          page: Search-page
          location: listing-1
        resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=

    ImpressionEvent:
      description: >
        A product has become visible to the consumer.
        In case you cannot send the impression when the product is visible, send us an impression event when the product was rendered in the HTML or if that's also not possible when your API returns the results.
        It is important to select the most specific event so that your vendors have more accurate CTR metrics, which allow them to better predict their campaigns.
      type: object
      required:
        - eventType
        - session
        - impressions
      properties:
        eventType:
          type: string
          description: Discriminator for the type of event.
          enum:
            - Impression
        session:
          $ref: '#/components/schemas/Session'
        impressions:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Impression'
          example:
            - resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
              id: 234f678-f90c
              placement:
                page: Search-page
                location: listing-1
            - resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
              placement:
                page: Search-page
                location: listing-2
        occurredAt:
          type: string
          format: date-time
          description: RFC3339 formatted timestamp including UTC offset
          example: '2022-01-23T12:34:56-05:00'

    Impression:
      type: object
      required:
        - placement
      properties:
        placement:
          $ref: '#/components/schemas/Placement'
        productId:
          type: string
          description: The product that was rendered.
          example: p_SA0238
        auctionId:
          type: string
          description: Required for promoted products. Must be the ID for the auction the product won.
          minLength: 1
          example: AKFU78
        id:
          type: string
          description: The marketplace's ID for the impression.
          minLength: 1
          example: 234f678-f90c
        resolvedBidId:
          type: string
          minLength: 1
          example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=

    PurchaseEvent:
      description: The consumer has purchased some products.
      type: object
      required:
        - eventType
        - session
        - id
        - purchasedAt
        - items
      properties:
        eventType:
          type: string
          description: Discriminator for the type of event.
          enum:
            - Purchase
        session:
          $ref: '#/components/schemas/Session'
        id:
          type: string
          description: The marketplace assigned ID for the order.
          minLength: 1
          example: o:567-123
        purchasedAt:
          type: string
          description: RFC3339 formatted timestamp including UTC offset
          example: '2021-10-12T07:20:50.52Z'
          format: date-time
        items:
          type: array
          description: Items purchased.
          minItems: 1
          items:
            $ref: '#/components/schemas/PurchaseItem'

    PurchaseItem:
      type: object
      required:
        - productId
        - unitPrice
      properties:
        productId:
          type: string
          description: The marketplace ID of the product being purchased.
          minLength: 1
          example: p_SA0238
        auctionId:
          type: string
          description: If known, the product's auction ID if the consumer clicked on a promoted link before purchasing.
          minLength: 1
          example: AKFU78
        quantity:
          type: integer
          minimum: 1
          default: 1
          description: Count of product purchased.
          example: 2
        unitPrice:
          type: integer
          minimum: 1
          description: The price of a single item in minor currency units. For example, in the US (currency code "USD") the unit price is specified in cents.
          example: 1295
        resolvedBidId:
          type: string
          minLength: 1
          example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
      example:
        productId: p_SA0238
        unitPrice: 1295
        resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=

    Event:
      oneOf:
        - $ref: '#/components/schemas/ImpressionEvent'
        - $ref: '#/components/schemas/ClickEvent'
        - $ref: '#/components/schemas/PurchaseEvent'

    ImpressionResponse:
      type: object
      properties:
        impressionId:
          type: string
          description: Topsort assigned ID for the impression.
          example: 70ed4d78-34aa-42c7-b6e2-6a670568b6e3
        id:
          type: string
          description: The marketplace's ID for the impression, if provided.
          example: 234f678-f90c
      required:
        - impressionId

    ImpressionsResponse:
      type: object
      properties:
        impressions:
          type: array
          description: The collection of all impressions that were processed correctly.
          items:
            $ref: '#/components/schemas/ImpressionResponse'
      example:
        impressions:
          - impressionId: 70ed4d78-34aa-42c7-b6e2-6a670568b6e3
            id: 234f678-f90c
          - impressionId: 41505d1d-c196-4fe5-a89d-fa3a2c8a94c2

    ClickResponse:
      type: object
      properties:
        clickId:
          type: string
          description: Topsort assigned ID for the click.
          example: 00b55a66-a221-4cdd-8c76-8e422558f1c3
        id:
          type: string
          description: The marketplace's ID for the click, if provided.
          example: 234f678-f90c
      required:
        - clickId

    PurchaseResponse:
      type: object
      properties:
        purchaseId:
          type: string
          description: Topsort assigned ID for the purchase.
          example: 3f15c9a5-5129-4359-b39c-099e273afe66
        id:
          type: string
          description: The marketplace's ID for the purchase, if provided.
          example: 234f678-f90c
      required:
        - purchaseId

    Slots:
      description:
        'The Slots object specifies how many auctions winners should be
        returned for each promotion type. The promotion types depend on
        the marketplace configuration. For sponsored listings, use the
        "listings" key.'
      type: object
      properties:
        listings:
          type: integer
          example: 2
          minimum: 1
      minProperties: 1

    Error:
      type: object
      required:
        - errCode
      properties:
        errCode:
          type: string
          description: A short string uniquely identifying the problem.
          enum:
            - bad_request
            - empty_request
            - internal_server_error
            - invalid_api_key
            - invalid_auction_id
            - invalid_event_type
            - invalid_promotion_type
            - invalid_session
            - missing_placement
            - missing_product_id
            - missing_promotion_type
            - missing_purchased_at
            - missing_session
            - missing_slots
            - no_products
            - no_purchase_items
            - purchase_item_quantity_less_or_equal_than_zero
            - resolved_bid_id_not_found
            - too_few_impressions
            - too_few_slots
        docUrl:
          type: string
          format: uri
          description: A link to a documentation page providing more information about the error.
          example: https://docs.topsort.com/reference/errors
        message:
          type: string
          description: >
            Human-readable explanation of or details about the error.
            The string for a given error may change over time; code should not parse or dispatch based on particular values for this field.

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer