Sovrn

Sovrn Commerce Merchant Group Summaries API

Retrieve the merchants a Commerce account is approved to work with, including geo-specific commission rates, rate formats, average EPC and order value, preferred-status flags and per-merchant domains. Filterable by name, group id, domain, geo, program type and category, with page/pageSize pagination, and paired with a delta endpoint that returns only merchants changed since a timestamp and supports If-None-Match / 304.

GitHub OpenAPI

Documentation

📖
APIReference
https://developer.sovrn.com/reference/post_summaries
📖
Documentation
https://developer.sovrn.com/reference/get_summaries-delta

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/sovrn/refs/heads/main/openapi/sovrn-merchant-summaries-openapi.yml

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/sovrn/refs/heads/main/overlays/sovrn-merchant-summaries-overlay.yaml

OpenAPI Specification

sovrn-merchant-summaries-openapi.yml Raw ↑ 
openapi: 3.0.0
info:
  title: Sovrn Commerce Merchant Group Summaries API
  version: 1.0.0
  description: Harvested verbatim from the OpenAPI definitions Sovrn publishes inside its Sovrn Developer
    Center reference pages at https://developer.sovrn.com/. Operations sharing this info/servers block
    were merged into one document by API Evangelist; operation content is unmodified.
  x-source-title: Merchant Group Summaries API
servers:
- url: https://viglink.io/merchants/rates
  description: Merchant Group Summaries API
components:
  securitySchemes:
    SecretKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'Authorization header using the Secret Key scheme. Format: "secret {secret key}"'
  schemas:
    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
    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'
    NetworkSummary:
      type: object
      properties:
        CPA:
          type: array
          items:
            $ref: '#/components/schemas/CPASummary'
        CPC:
          $ref: '#/components/schemas/CPCSummary'
    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
    MerchantRateDto:
      type: object
      properties:
        currentRate:
          type: number
          format: double
        rateFormat:
          type: string
        action:
          type: string
        details:
          type: string
    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
    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
    MerchantGroupSummaryFilterType:
      type: string
      enum:
      - NAME
      - GROUP_ID
      - CATEGORY
      - GEO
      - PROGRAM_TYPE
      - DOMAIN
paths:
  /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
  /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