Vouchers API

Overview

Vouchers API allows you to access advertiser voucher codes through a REST API. By using the API, you can for example:

• Dynamically access fresh voucher code information.
• Automate the process of updating voucher codes on your site.
• Match voucher codes against content on your site.
• Build rich banner widgets with voucher code information.
• Allow advertisers to create custom vouchers for you.

Don´t have a publisher account? Register here and get started today!

This documentation is intended for publishers. If you are an advertiser, please go to the advertiser documentation.

Authentication

In order to access the Vouchers API, you need a publisher account with Tradedoubler. Signing up for an account takes approximately 2 minutes by filling out this form.

Once you have an account and a site, you can pick up your unique token by logging on and navigating to "Account" > "Manage tokens". The token for Vouchers API is under the system "VOUCHERS".

Tokens are 40 character hexadecimal SHA-1 strings.

CORS

The domain api.tradedoubler.com is CORS enabled, meaning that you can use client side XMLHttpRequest without getting any cross-domain security issues.

Please note however that CORS is not yet fully implemented in all browsers, so you may want to go for JSONP for client side requests.

Matrix syntax

Generally, all services in Tradedoubler APIs use the matrix syntax .

However, top level and service irrelevant information is sent as regular URL parameters. Usually, these are token and jsonp.

Get vouchers service

This is the syntax to get vouchers:

HTTP[S] GET https://api.tradedoubler.com/1.0/vouchers[.empty|json|xml][query keys]?token={token}[&jsonp=myCallback]

Optional query keys

You can add a query to your request if you want to filter the results.

*If you are using multiple values for one particular key, use one key for each value.

See Example requests sample GET queries.

Voucher type ID

These are the six voucher type IDs, used for creating and searching for vouchers:

JSON/JSONP

If you specify .json as extension, the API will return JSON.

You can also add a key named jsonp to your request and get a JSONP Javascript function returned. The jsonp key's value becomes the callback funcation name. For example jsonp=myCallback:

function myCallback(result, statusCode, message)

JSONP callback function argument definitions:

If you do not define a callback name and specify json as extention, the API will return actual JSON with MIME type application/json.

See example responses for more information.

Example requests

Get all active vouchers in XML:

HTTP[S] GET http://api.tradedoubler.com/1.0/vouchers.xml?token={token}

Get all vouchers that are active at least till xmas eve 2012 in JSON:

HTTP[S] GET http://api.tradedoubler.com/1.0/vouchers.json;minEndDate=1356393599000?token={token}

Get all raffle or discount vouchers owned by program ID 50000 in JSONP with a callback named myCallback:

HTTP[S] GET http://api.tradedoubler.com/1.0/vouchers.xml;voucherTypeId=2;voucherTypeId=5;programId=50000?token={token}&jsonp=myCallback

Get all vouchers connected to your site particularly:

HTTP[S] GET http://api.tradedoubler.com/1.0/vouchers.xml;siteSpecific=true?token={token}

Get 10 vouchers from the second page matching the word "free" in XML:

HTTP[S] GET http://api.tradedoubler.com/1.0/vouchers.xml;pageSize=10;page=1;keywords=free?token={token}

Response expectations

As a response to your request, you can expect the following data.

See Error management for details on error messages.

XML response

This is an example of a voucher returned as XML:

<voucherList>
	<voucher>
		<id>16043</id>
		<programId>15603</programId>
		<programName>Voucher program</programName>
		<code>XS51F9</code>
		<updateDate>1362420096992</updateDate>
		<publishStartDate>1362351600000</publishStartDate>
		<publishEndDate>1364511599999</publishEndDate>
		<startDate>1362351600000</startDate>
		<endDate>1364511599999</endDate>
		<title>Save dollars today!</title>
		<shortDescription>10% off your purchase</shortDescription>
		<description>Save 10% off your purchase by using this voucher code!</description>
		<voucherTypeId>1</voucherTypeId>
		<defaultTrackUri>http://clk.tradedoubler.com/click?a(11111)p(15603)ttid(13)url(http://www.advertiser.co.uk/affiliate-landing)</defaultTrackUri>
		<siteSpecific>false</siteSpecific>
		<landingUrl>http://www.advertiser.co.uk/affiliate-landing</landingUrl>
		<discountAmount>10</discountAmount>
		<isPercentage>true</isPercentage>
		<exclusive>false</exclusive>
	</voucher>
</voucherList>

JSON response

This is the same voucher as above, formatted as Json:

{
	"id": 16043,
	"programId": 15603,
	"programName": "Voucher program",
	"code": "XS51F9",
	"updateDate": "1362420096992",
	"publishStartDate": "1362351600000",
	"publishEndDate": "1364511599999",
	"startDate": "1362351600000",
	"endDate": "1364511599999",
	"title": "Save dollars today!",
	"shortDescription": "10% off your purchase",
	"description": "Save 10% off your purchase by using this voucher code!",
	"voucherTypeId": 1,
	"defaultTrackUri": "http://clk.tradedoubler.com/click?a(11111)p(15603)ttid(13)url(http://www.advertiser.co.uk/affiliate-landing)",
	"siteSpecific": false,
	"landingUrl": "http://www.advertiser.co.uk/affiliate-landing",
	"discountAmount": 10,
	"isPercentage": true,
	"exclusive": false,
}

JSONP response (callback=myCallback):

myCallback ([
	{
		"id": 16043,
		"programId": 15603,
		"programName": "Voucher program",
		"code": "XS51F9",
		"updateDate": "1362420096992",
		"publishStartDate": "1362351600000",
		"publishEndDate": "1364511599999",
		"startDate": "1362351600000",
		"endDate": "1364511599999",
		"title": "Save dollars today!",
		"shortDescription": "10% off your purchase",
		"description": "Save 10% off your purchase by using this voucher code!",
		"voucherTypeId": 1,
		"defaultTrackUri": "http://clk.tradedoubler.com/click?a(11111)p(15603)ttid(13)url(http://www.advertiser.co.uk/affiliate-landing)",
		"siteSpecific": false,
		"landingUrl": "http://www.advertiser.co.uk/affiliate-landing",
		"discountAmount": 10,
		"isPercentage": true,
		"exclusive": false,
	}
]);

Example code

This button asynchronously fetches voucher JSON data by using a simple jQuery Ajax CORS">CORS request to Tradedoubler.

Click to fetch vouchers!

This is the function that is called when the button is clicked. The variable voucherExample is the <tbody> element of the table that is used to present the content.

function getVouchers() {
  $("#voucherExampleTable").hide(); //hides the table when loading results
  $.ajax({
    type: "GET",
    url: "http://api.tradedoubler.com/1.0/vouchers.json;pageSize=10?token=B73AE30C600218523B4DE65A97C01A8309535FD5", //request to Tradedoubler. Make sure to use your own token.
    dataType: "json",
    success: function (data) {
      var hits = data.length;
      if (hits==0) {
          //no hits :(
          var tr=document.createElement("tr");
            var td=document.createElement("td");
            td.setAttribute("colspan","5");
            td.innerHTML = "Found no vouchers :(";
            tr.appendChild(td);
          document.getElementById("voucherExample").appendChild(tr);
      } else {
        for (var i=0; i<data.length; i++) { //loop through vouchers
          var tr=document.createElement("tr");
            for (var x=0; x<5; x++) { //create a td for each value we want to present
              var td=document.createElement("td");
              switch (x) {
                case 0 : td.innerHTML = data[i].programName; break;
                case 1 : td.innerHTML = data[i].title; break;
                case 2 : td.innerHTML = data[i].shortDescription; break;
                case 3 : td.innerHTML = data[i].code; break;
                case 4 : td.innerHTML = "<a href=\""+data[i].defaultTrackUri+"\" target=\"_blank\">Click</a>"; break;
              }
              tr.appendChild(td);
            }
          document.getElementById("voucherExample").appendChild(tr);
        }
      }
      $("#voucherExampleTable").fadeIn(); //show table when done
    }
  });
}

Error management

When an error occurs in the API, we try to describe the problem in detail.

Other than the above, you can get generic HTTP errors. These are described here by W3C

The most common HTTP errors are: