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).