openapi: 3.0.0
info:
  title: Bid Check Account Merchant Group Summaries API
  version: 1.0.0
  description: 'Use Bid Check during the click redirect flow to request a real-time bid from Sovrn for a destination URL. When Sovrn can monetize the click, Bid Check returns a redirect URL that you can use to redirect the user.


    Partners typically use Bid Check when comparing offers from multiple affiliate networks in real time. After receiving Sovrn''s bid, you can decide whether to route the click through Sovrn or through another network.


    For CPC bids, the returned `eepc` is the rate you can earn by routing the click through Sovrn before the bid expires. Sovrn''s revenue share has already been deducted from this value. For CPA offers, `eepc` is the average amount Sovrn expects you to earn per click and is not guaranteed for an individual click.


    **Note on URL encoding:** query parameter values, especially `out`, `userAgent`, `referrerUrl`, `subId`, and tracking values that contain spaces or reserved characters, must be URL-encoded when constructing the request. The `example` values below show the raw decoded form; your HTTP client or the ReadMe "Try It" panel will encode them automatically.

    '
  x-source: https://developer.sovrn.com/llms.txt (per-endpoint OpenAPI definitions, harvested 2026-07-21)
servers:
- url: https://api.viglink.com
  description: Production
tags:
- name: Merchant Group Summaries
paths:
  /summaries:
    post:
      summary: Approved Merchants
      description: This endpoint is used to retrieve all approved merchants you can work with, including geo-specific rates and performance metrics.
      tags:
      - Merchant Group Summaries
      security:
      - SecretKey: []
      parameters:
      - name: campaignId
        in: query
        required: true
        description: ID of the user/campaign to view potential merchants for
        schema:
          type: integer
          format: int64
      - name: Accept-Encoding
        in: header
        required: false
        description: Indicates the optional encoding (compression) algorithm the client can understand
        schema:
          type: string
          enum:
          - gzip
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantGroupSummaryRequest'
            examples:
              sampleRequest:
                summary: A sample request with optional filters
                value:
                  filters:
                  - type: GROUP_ID
                    values:
                    - 34
                    - 384
                  - type: CATEGORY
                    values:
                    - SF
                    - CE
                  - type: PROGRAM_TYPE
                    values:
                    - CPA
                  - type: GEO
                    values:
                    - us
                    - ca
                  page: 1
                  pageSize: 20
      responses:
        '200':
          description: Successful operation
          headers:
            ETag:
              schema:
                type: string
              description: ETag for caching purposes
            Last-Modified:
              schema:
                type: string
                format: date-time
              description: Timestamp of when the resource was last modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IOCollectionResponse'
              examples:
                sampleResponse:
                  summary: A sample response
                  value:
                    results:
                    - groupId: 12345
                      name: Merchant A
                      description: Pet retailer
                      terms: Standard terms apply
                      sovrnPreferred: true
                      logoImageUrl: https://example.com/logo.png
                      category:
                      - PT
                      - AU
                      sovrn:
                        CPA:
                        - geo: US
                          averageEpc: 0.15
                          averageOrderValue: 75.5
                          calculatedCommissionRate: 0.08
                          rates:
                          - currentRate: 8
                            rateFormat: PERCENTAGE
                            action: Sale
                            details: 8% on all sales
                          domains:
                          - merchanta.com
                        CPC:
                          calculatedEpc: 0.25
                    page: 1
                    perPage: 20
                    totalItems: 100
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: User not found
        '429':
          description: Too many requests (rate limit exceeded)
        '500':
          description: Internal server error
  /summaries/delta:
    get:
      summary: Merchant Updates
      description: This endpoint retrieves only the updated merchants since your last query, including geo-specific rates and performance metrics.
      tags:
      - Merchant Group Summaries
      security:
      - SecretKey: []
      parameters:
      - name: campaignId
        in: query
        required: true
        description: ID of the user/campaign to view potential merchants for
        schema:
          type: integer
          format: int64
      - name: page
        in: query
        required: false
        description: The page number of results to view
        schema:
          type: integer
          default: 1
      - name: pageSize
        in: query
        required: false
        description: The page size of results to view
        schema:
          type: integer
          default: 1000
      - name: since
        in: query
        required: false
        description: Required if 'If-None-Match' is not provided. Filter results updated since this datetime (ISO 8601 format). Note
        schema:
          type: string
          format: date-time
          example: '2023-04-01T00:00:00Z'
      - name: If-None-Match
        in: header
        required: false
        description: Required if 'since' is not provided. ETag header for cache validation
        schema:
          type: string
      - name: Accept-Encoding
        in: header
        required: false
        description: Indicates the optional encoding (compression) algorithm the client can understand
        schema:
          type: string
          enum:
          - gzip
      responses:
        '200':
          description: Successfully retrieved merchant group summaries
          headers:
            ETag:
              schema:
                type: string
              description: ETag for caching purposes
            Last-Modified:
              schema:
                type: string
                format: date-time
              description: Timestamp of when the resource was last modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IOCollectionResponse'
        '304':
          description: No changes since the specified timestamp
          headers:
            Last-Modified:
              schema:
                type: string
                format: date-time
              description: Timestamp of when the resource was last modified
        '400':
          description: Bad request parameters
        '401':
          description: Unauthorized request
        '404':
          description: Resource not found
        '429':
          description: Too many requests (rate limit exceeded)
        '500':
          description: Internal server error
components:
  schemas:
    MerchantGroupSummaryFilterType:
      type: string
      enum:
      - NAME
      - GROUP_ID
      - CATEGORY
      - GEO
      - PROGRAM_TYPE
      - DOMAIN
    MerchantRateDto:
      type: object
      properties:
        currentRate:
          type: number
          format: double
        rateFormat:
          type: string
        action:
          type: string
        details:
          type: string
    NetworkSummary:
      type: object
      properties:
        CPA:
          type: array
          items:
            $ref: '#/components/schemas/CPASummary'
        CPC:
          $ref: '#/components/schemas/CPCSummary'
    MerchantGroupSummaryResponse:
      type: object
      properties:
        groupId:
          type: integer
          format: int64
        name:
          type: string
        description:
          type: string
        terms:
          type: string
        sovrnPreferred:
          type: boolean
        logoImageUrl:
          type: string
        category:
          type: array
          items:
            type: string
            enum:
            - CE
            - AU
            - FS
            - HB
            - RU
            - AE
            - SF
            - SH
            - TV
            - FI
            - PT
            - CM
            - BK
            - ED
            - OT
            - DT
            - MM
            - FD
            - HG
            - AG
            - CA
            - CB
            - EM
            - FB
            - FH
            - GM
            - JW
            - LF
            - MP
            - SP
            - HO
            - CP
            - UN
        sovrn:
          $ref: '#/components/schemas/NetworkSummary'
    MerchantGroupSummaryFilter:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/MerchantGroupSummaryFilterType'
        values:
          type: array
          items:
            type: integer
          description: 'For GROUP_ID: Enter numbers directly (e.g., 384)

            For all other filters: Enter text values - the red highlight can be ignored for non-GROUP_ID filters

            '
      required:
      - type
      - values
    CPASummary:
      type: object
      properties:
        geo:
          type: string
        averageEpc:
          type: number
          format: float
        averageOrderValue:
          type: number
          format: float
        calculatedCommissionRate:
          type: number
          format: float
        rates:
          type: array
          items:
            $ref: '#/components/schemas/MerchantRateDto'
        domains:
          type: array
          items:
            type: string
    CPCSummary:
      type: object
      properties:
        calculatedEpc:
          type: number
          format: float
    IOCollectionResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/MerchantGroupSummaryResponse'
        page:
          type: integer
          format: int32
        perPage:
          type: integer
          format: int32
        totalItems:
          type: integer
          format: int32
    MerchantGroupSummaryRequest:
      type: object
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/MerchantGroupSummaryFilter'
        page:
          type: integer
          minimum: 1
          default: 1
        pageSize:
          type: integer
          minimum: 1
          maximum: 2500
          default: 1000
      required:
      - page
      - pageSize