openapi: 3.0.1
info:
  title: Awin API
  description: >-
    Documented public REST API for the Awin global affiliate marketing network.
    Publishers and advertisers pull individual transactions and aggregated
    performance reports, read commission groups and programme details, and list
    the accounts a user can access. All endpoints are served over HTTPS only,
    return JSON, and authenticate with an OAuth 2.0 Bearer access token issued at
    the user level from the Awin UI. A platform throttle limits usage to 20 API
    calls per minute per user. Endpoints and parameters below are grounded in the
    public Awin API documentation at help.awin.com/apidocs.
  termsOfService: https://www.awin.com/gb/legal
  contact:
    name: Awin API Support
    url: https://help.awin.com/apidocs/introduction-1
  version: '1.0'
servers:
  - url: https://api.awin.com
    description: Awin API (HTTPS only)
security:
  - bearerAuth: []
tags:
  - name: Accounts
    description: Accounts the authenticated user can access.
  - name: Transactions
    description: Individual publisher and advertiser transactions.
  - name: Reports
    description: Aggregated performance reports.
  - name: Commission Groups
    description: Commission groups and rates for a programme.
  - name: Programmes
    description: Advertiser programmes and their details.
paths:
  /accounts:
    get:
      operationId: getAccounts
      tags:
        - Accounts
      summary: Get accounts for the authenticated user
      description: >-
        Return the list of accounts associated with the user. Because tokens are
        user-level, this enumerates every publisher and advertiser account the
        user can access.
      parameters:
        - $ref: '#/components/parameters/accessToken'
        - name: type
          in: query
          required: false
          description: Filter by account type.
          schema:
            type: string
            enum: [publisher, advertiser]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
  /publishers/{publisherId}/transactions/:
    get:
      operationId: getPublisherTransactions
      tags:
        - Transactions
      summary: Get list of transactions for a publisher
      description: >-
        Pull individual transactions for a publisher over a date range of up to
        31 days. Times use the yyyy-MM-ddThh:mm:ss format in the given timezone.
      parameters:
        - $ref: '#/components/parameters/publisherId'
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/startDateTime'
        - $ref: '#/components/parameters/endDateTime'
        - $ref: '#/components/parameters/timezone'
        - $ref: '#/components/parameters/dateTypeTx'
        - $ref: '#/components/parameters/statusTx'
        - $ref: '#/components/parameters/showBasketProducts'
        - name: advertiserId
          in: query
          required: false
          description: Single advertiser ID or comma-separated list.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
  /advertisers/{advertiserId}/transactions/:
    get:
      operationId: getAdvertiserTransactions
      tags:
        - Transactions
      summary: Get list of transactions for an advertiser
      description: >-
        Pull individual transactions for an advertiser over a date range of up to
        31 days.
      parameters:
        - $ref: '#/components/parameters/advertiserId'
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/startDateTime'
        - $ref: '#/components/parameters/endDateTime'
        - $ref: '#/components/parameters/timezone'
        - $ref: '#/components/parameters/dateTypeTx'
        - $ref: '#/components/parameters/statusTx'
        - $ref: '#/components/parameters/showBasketProducts'
        - name: publisherId
          in: query
          required: false
          description: Single publisher ID or comma-separated list.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
  /publishers/{publisherId}/reports/advertiser:
    get:
      operationId: getPublisherAdvertiserReport
      tags:
        - Reports
      summary: Advertiser performance report for a publisher
      description: Aggregated performance for a publisher, broken down by advertiser.
      parameters:
        - $ref: '#/components/parameters/publisherId'
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
        - $ref: '#/components/parameters/region'
        - $ref: '#/components/parameters/timezoneOptional'
        - $ref: '#/components/parameters/dateTypeReport'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PerformanceRow'
  /publishers/{publisherId}/reports/creative:
    get:
      operationId: getPublisherCreativeReport
      tags:
        - Reports
      summary: Creative performance report for a publisher
      description: Aggregated transactions, clicks, and impressions by creative for a publisher.
      parameters:
        - $ref: '#/components/parameters/publisherId'
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
        - $ref: '#/components/parameters/region'
        - $ref: '#/components/parameters/timezoneOptional'
        - $ref: '#/components/parameters/dateTypeReport'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PerformanceRow'
  /publishers/{publisherId}/reports/campaign:
    get:
      operationId: getPublisherCampaignReport
      tags:
        - Reports
      summary: Campaign performance report for a publisher
      description: >-
        Aggregated clicks and transactions by campaign and advertiser for a
        publisher, listable in day, month, or year intervals.
      parameters:
        - $ref: '#/components/parameters/publisherId'
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
        - $ref: '#/components/parameters/timezoneOptional'
        - $ref: '#/components/parameters/dateTypeReport'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PerformanceRow'
  /advertisers/{advertiserId}/reports/publisher:
    get:
      operationId: getAdvertiserPublisherReport
      tags:
        - Reports
      summary: Publisher performance report for an advertiser
      description: Aggregated performance for an advertiser, broken down by publisher.
      parameters:
        - $ref: '#/components/parameters/advertiserId'
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
        - $ref: '#/components/parameters/timezone'
        - $ref: '#/components/parameters/dateTypeReport'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PerformanceRow'
  /advertisers/{advertiserId}/reports/creative:
    get:
      operationId: getAdvertiserCreativeReport
      tags:
        - Reports
      summary: Creative performance report for an advertiser
      description: Aggregated transactions, clicks, and impressions by creative for an advertiser.
      parameters:
        - $ref: '#/components/parameters/advertiserId'
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
        - $ref: '#/components/parameters/region'
        - $ref: '#/components/parameters/timezoneOptional'
        - $ref: '#/components/parameters/dateTypeReport'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PerformanceRow'
  /advertisers/{advertiserId}/reports/campaign:
    get:
      operationId: getAdvertiserCampaignReport
      tags:
        - Reports
      summary: Campaign performance report for an advertiser
      description: >-
        Aggregated clicks and transactions by campaign and publisher for an
        advertiser, listable in day, month, or year intervals.
      parameters:
        - $ref: '#/components/parameters/advertiserId'
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
        - $ref: '#/components/parameters/timezoneOptional'
        - $ref: '#/components/parameters/dateTypeReport'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PerformanceRow'
  /publishers/{publisherId}/commissiongroups:
    get:
      operationId: getCommissionGroups
      tags:
        - Commission Groups
      summary: Get commission groups for an advertiser programme
      description: >-
        Return all commission groups of a programme along with the commission
        values a publisher earns.
      parameters:
        - $ref: '#/components/parameters/publisherId'
        - $ref: '#/components/parameters/accessToken'
        - name: advertiserId
          in: query
          required: true
          description: The advertiser identifier.
          schema:
            type: integer
        - name: effectiveDate
          in: query
          required: false
          description: ISO-8601 timestamp to retrieve historical rates.
          schema:
            type: string
            format: date-time
        - name: extraConditionsDetails
          in: query
          required: false
          description: Include condition values when true.
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  commissionGroups:
                    type: array
                    items:
                      $ref: '#/components/schemas/CommissionGroup'
  /publishers/{publisherId}/programmes:
    get:
      operationId: getProgrammes
      tags:
        - Programmes
      summary: Get programmes for a publisher
      description: >-
        List the advertiser programmes a publisher has a relationship with,
        filtered by relationship and optionally by country.
      parameters:
        - $ref: '#/components/parameters/publisherId'
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/relationship'
        - name: countryCode
          in: query
          required: false
          description: Two-letter country code to filter programmes.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProgrammeInfo'
  /publishers/{publisherId}/programmedetails:
    get:
      operationId: getProgrammeDetails
      tags:
        - Programmes
      summary: Get programme details for a publisher
      description: >-
        Return detail for a single advertiser programme including description,
        membership status, valid domains, KPIs, and the commission range across
        commission groups.
      parameters:
        - $ref: '#/components/parameters/publisherId'
        - $ref: '#/components/parameters/accessToken'
        - name: advertiserId
          in: query
          required: true
          description: The advertiser identifier.
          schema:
            type: integer
        - $ref: '#/components/parameters/relationship'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProgrammeDetails'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        OAuth 2.0 user-level access token generated at ui.awin.com/awin-api and
        sent as an Authorization Bearer header. The Create Transactions API is
        the exception and uses an x-api-key header instead. Many endpoints also
        accept the token as an accessToken query parameter.
  parameters:
    accessToken:
      name: accessToken
      in: query
      required: true
      description: User-level access token (also accepted as an Authorization Bearer header).
      schema:
        type: string
    publisherId:
      name: publisherId
      in: path
      required: true
      description: The publisher account identifier.
      schema:
        type: integer
    advertiserId:
      name: advertiserId
      in: path
      required: true
      description: The advertiser account identifier.
      schema:
        type: integer
    startDateTime:
      name: startDate
      in: query
      required: true
      description: Start of range, format yyyy-MM-ddThh:mm:ss. Max 31 days between start and end.
      schema:
        type: string
    endDateTime:
      name: endDate
      in: query
      required: true
      description: End of range, format yyyy-MM-ddThh:mm:ss. Max 31 days between start and end.
      schema:
        type: string
    startDate:
      name: startDate
      in: query
      required: true
      description: Start date, format yyyy-MM-dd.
      schema:
        type: string
        format: date
    endDate:
      name: endDate
      in: query
      required: true
      description: End date, format yyyy-MM-dd.
      schema:
        type: string
        format: date
    timezone:
      name: timezone
      in: query
      required: true
      description: Timezone identifier, e.g. UTC, Europe/London, US/Eastern.
      schema:
        type: string
    timezoneOptional:
      name: timezone
      in: query
      required: false
      description: Timezone identifier, defaults to UTC.
      schema:
        type: string
        default: UTC
    region:
      name: region
      in: query
      required: true
      description: >-
        Region code. One of AT, AU, BE, BR, BU, CA, CH, DE, DK, ES, FI, FR, GB,
        IE, IT, NL, NO, PL, SE, US.
      schema:
        type: string
    dateTypeTx:
      name: dateType
      in: query
      required: false
      description: Which date to filter transactions on.
      schema:
        type: string
        enum: [transaction, validation, amendment]
        default: transaction
    dateTypeReport:
      name: dateType
      in: query
      required: false
      description: Which date to aggregate the report on.
      schema:
        type: string
        enum: [transaction, validation]
        default: transaction
    statusTx:
      name: status
      in: query
      required: false
      description: Filter transactions by status.
      schema:
        type: string
        enum: [pending, approved, declined, deleted]
    showBasketProducts:
      name: showBasketProducts
      in: query
      required: false
      description: Include basket products when product-level tracking is enabled.
      schema:
        type: boolean
        default: false
    relationship:
      name: relationship
      in: query
      required: false
      description: Filter by the publisher's relationship to the programme.
      schema:
        type: string
        enum: [joined, pending, suspended, rejected, notjoined, any]
        default: joined
  schemas:
    Account:
      type: object
      properties:
        accountId:
          type: integer
          description: Account ID as known from the frontend URLs.
        accountName:
          type: string
          description: Programme name for advertisers, company name for publishers.
        accountType:
          type: string
          enum: [publisher, advertiser]
        userRole:
          type: string
          description: The permission level assigned to the user for this account.
    Transaction:
      type: object
      properties:
        id:
          type: integer
        url:
          type: string
        advertiserId:
          type: integer
        publisherId:
          type: integer
        commissionSharingPublisherId:
          type: integer
        siteName:
          type: string
        commissionStatus:
          type: string
          enum: [pending, approved, declined, deleted]
        commissionAmount:
          $ref: '#/components/schemas/Money'
        saleAmount:
          $ref: '#/components/schemas/Money'
        ipHash:
          type: string
        customerCountry:
          type: string
        clickRefs:
          type: object
          description: clickRef and clickRef2 through clickRef6.
        clickDate:
          type: string
          format: date-time
        transactionDate:
          type: string
          format: date-time
        validationDate:
          type: string
          format: date-time
        type:
          type: string
          description: Transaction type, e.g. Sale, Lead, Bonus, Mobile App Install.
        declineReason:
          type: string
        voucherCodeUsed:
          type: boolean
        voucherCode:
          type: string
        lapseTime:
          type: integer
          description: Conversion time in seconds.
        amended:
          type: boolean
        orderRef:
          type: string
        customParameters:
          type: array
          items:
            type: object
        transactionParts:
          type: array
          items:
            type: object
        paidToPublisher:
          type: boolean
        basketProducts:
          type: array
          items:
            type: object
    Money:
      type: object
      properties:
        amount:
          type: number
        currency:
          type: string
    PerformanceRow:
      type: object
      description: One aggregated performance row for a report dimension.
      properties:
        advertiserId:
          type: integer
        advertiserName:
          type: string
        publisherId:
          type: integer
        publisherName:
          type: string
        region:
          type: string
        currency:
          type: string
        impressions:
          type: integer
        clicks:
          type: integer
        pendingNo:
          type: integer
        pendingValue:
          type: number
        pendingComm:
          type: number
        confirmedNo:
          type: integer
        confirmedValue:
          type: number
        confirmedComm:
          type: number
        bonusNo:
          type: integer
        bonusValue:
          type: number
        bonusComm:
          type: number
        declinedNo:
          type: integer
        declinedValue:
          type: number
        declinedComm:
          type: number
        totalNo:
          type: integer
        totalValue:
          type: number
        totalComm:
          type: number
    CommissionGroup:
      type: object
      properties:
        groupId:
          type: integer
        groupName:
          type: string
        groupCode:
          type: string
        type:
          type: string
          enum: [fix, percentage]
        amount:
          type: number
          description: Commission value for fixed-rate types.
        percentage:
          type: number
          description: Commission value for percentage-based types.
        currency:
          type: string
        ratesStart:
          type: string
          format: date-time
        ratesEnd:
          type: string
          format: date-time
        conditions:
          type: array
          items:
            type: object
    ProgrammeInfo:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        displayUrl:
          type: string
        clickThroughUrl:
          type: string
        deeplinkEnabled:
          type: boolean
        membershipStatus:
          type: string
        logoUrl:
          type: string
        currencyCode:
          type: string
        primaryRegion:
          type: object
        validDomains:
          type: array
          items:
            type: string
    ProgrammeDetails:
      type: object
      properties:
        programmeInfo:
          $ref: '#/components/schemas/ProgrammeInfo'
        kpi:
          type: object
          properties:
            averagePaymentTime:
              type: number
            approvalPercentage:
              type: number
            epc:
              type: number
            conversionRate:
              type: number
            validationDays:
              type: integer
            awinIndex:
              type: number
        commissionRange:
          type: array
          items:
            type: object
            properties:
              min:
                type: number
                description: Minimal commission across commission groups.
              max:
                type: number
                description: Maximum commission across commission groups.
              type:
                type: string
                description: percentage or amount (amount in programme currency).