API Post Offers

From Wiki

Jump to: navigation, search

Contents

POST Offers

Offers API allows publishers to retrieve details of promotions and voucher codes offered by Advertisers who are part of the Awin network. Publishers are able to retrieve offers published by advertisers they are both joined and aren't joined to. The data reflects that which is available in "My Offers" section on the Awin UI.
Due to implemented pagination, there is no limit on the amount of offers that can be retrieved with one API call.

Who can use it?

Publishers

Authentication

To authenticate, an API key should be provided in a header.
Details of this header and how to get your API key are described in our Wiki: API authentication and authorization.

Performing queries

Querying the API requires a POST request to a URL of this form:
https://api.awin.com/publisher/publisherId/promotions
Here, <publisherId> is the ID of your publisher account.

At minimum this request should include:

Filters

To specify the promotions you would like to be returned, a JSON object is passed in the request body.

Example

{
  "filters": {
    "advertiserIds": [1001, 1234],
    "exclusiveOnly": true,
    "membership": "joined",
    "regionCodes": ["GB", "DE", "US"],
    "status": "active",
    "type": "promotion",
    "updatedSince": "2022-05-06"
  },
  "pagination": {
    "page": 1,
    "pageSize": 10
  }
}


Field name Type Description
advertiserIds Array of integers
Limits the response to just the offers belonging to the specified Advertisers.
exclusiveOnly Boolean
Whether to limit the response to only those offers which are exclusive to your publisher account.
membership String
Possible values: “all”, “joined”, “notJoined”
Limits the offers returned based on your Membership status with the Advertiser.
Default: “all”
regionCodes Array of Strings
This should contain 2-letter country codes (ISO 3166 Alpha-2).
If this field is present, it limits the response to only offers which are valid in one or more of the specified regions.
status String
“active”: Offers which are currently valid.
“expiringSoon”: Offers which are currently valid, but will expire in the next 7 days.
“upcoming”: Offers which are not yet valid (their startDate is in the future).
Default: “active”
type String
Possible values: “promotion”, “voucher”, “all”
Default: “all”
updatedSince String (YYYY-MM-DD)
If present, this field will limit the returned offers to only those which have been created or modified since the specified date.
Example: “2022-05-06”
pageSize Integer
If present, this field will limit the count of returned offers to the specified number (between 10 and 200) per page. If not specified (up to) 200 offers are returned by default.
Example: “10”

Response

If the request is valid, authenticated and authorised, a 200 response code will be given. The response body will be a JSON object containing 2 properties:

  • data: an array of zero or more Offer objects (to a maximum of 200).
  • pagination: an object giving pagination information

Example

{
  “data”: [
    {
      "promotionId": 123456,
      "type": "voucher",
      "advertiser": {
        "id": 1001,
        "name": "Example Advertiser",
        "joined": true
      },
      "title": "10% Off",
      "description": "An Extra 10% off Everything!",
      "terms": "Limited time only, see website for details",
      "startDate": "2022-04-21T12:20:00+00:00",
      "endDate": "2022-04-25T23:59:00+00:00",
      "url": "https://www.example.com/",
      "urlTracking": "https://www.awin1.com/cread.php?...",
      "dateAdded": "2022-04-21T12:16:11+00:00",
      "campaign": "",
      "regions": {
        "all": false,
        "list": [
            {
              "name": "United Kingdom",
              "countryCode": "GB"
            }
        ]
      },
      "voucher": {
        "code": "EXTRA10",
        "exclusive": false,
        "attributable": false
      }
    },
 
  ],
  "pagination”: {
    "page": 1,
    "pageSize": 200,
    "total": 16792
  }
}


Field name Type Description
promotionId Integer
The unique ID of the promotion
type String
Possible values: “promotion” or “voucher”
advertiser Object
id: Integer. The Advertiser ID
name: String. The Advertiser name
joined: Boolean. Whether your publisher account has an active membership with this Advertiser.
title String
The title of the offer
description String The description of the offer
terms String
Terms and conditions relating to this offer
startDate, endDate String (YYYY-MM-DDT00:00:00.000)
Dates defining the offer's active period. Time is in UTC.
dateAdded String (YYYY-MM-DDT00:00:00.000) The date the offer has been added to the Awin network. Time is in UTC.
url String
URL of the page where the offer can be found – e.g. a product page.
urlTracking String
Awin tracking URL to the same page.
regions Object
all: Boolean. If true, then the offer is applicable in all regions (and the list property will be absent).
list: Array of Objects. Denotes the regions in which the offer is applicable. Properties: name, countryCode.
voucher Object
This property will only be present if the offer is of type “voucher”.
code: String. The voucher code, to be entered on the Advertiser’s checkout page.
If there is no membership with the advertiser, this value will be null – the publisher should join the Advertiser programme in order to have visibility of the voucher code.
exclusive: Boolean. Whether this voucher code is exclusive to your publisher account.
attributable: Whether the use of this voucher code will automatically attribute the sale to your publisher account, regardless of tracking links used.

Privacy

Due to new European legislation regarding how websites store information about you, AWIN is updating its privacy policy. You can see the new version of our policy here. If you would like to see the information we capture on this website, please click here for further details. In order to accept cookies on this site please click the 'I ACCEPT' button