Vouchers Open API

Dynamically access fresh voucher code data from Tradedoubler advertisers.

Overview

Vouchers Open API is the first module of Open API. You can 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 Open 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 Open API is under the system "VOUCHERS".

Examples in this document use {token} as a placeholder to where you should place your token when building a request.

Also on the Manage tokens page, you will find your Products-related tokens. Read more about the Products Open API here.

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 Open API 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.

Name Description Type Multiple*
id Primary key of the voucher Integer Yes
maxStartDate Start date in UNIX Epoch time milliseconds or ISO8601 (e.g. 2012-12-24T16:00:00Z) Integer No
minEndDate End date in UNIX Epoch time milliseconds or ISO8601 (e.g. 2012-12-24T16:00:00Z) Integer No
dateOutputFormat Set to 'iso8601' if you want dates returned in ISO8601 format String No
programId Primary key of the program the voucher corresponds to Integer Yes
keywords Matches title, description, short description and code String Yes
voucherTypeId Primary key of the type. See table for specification Integer Yes
siteSpecific Set to True if you only want to get your exclusive voucher codes Boolean No
pageSize Number of items to return. Defaults to 1000 Integer No
page If you get more items than pageSize, you can use this key to specify which page you want returned. For example, if you get 100 results and pageSize is 10, setting page to 2 will get you products 21-30. Integer No
random Enter a seed to get a specific randomized order of your result Integer No
languageId Enter an ISO 639-1 code to filter on language. String No
jsonp string No

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

Correct: id=1;id=2;id=3
Incorrect: id=1,2,3

See Example requests sample GET queries.

Voucher type ID

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

ID Name Description
1 Voucher Offer usable only with a voucher code. This type has a voucher code.
2 Discount General discount without a voucher code. This type must always include a discount amount.
3 Free article Free item(s) offered on purchase.
4 Free shipping Free shipping offered without a voucher code.
5 Raffle Competition or lottery connected to a purchase.

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:

Name Description Type
result The result JSON as an evaluated javascript object object/array
statusCode HTTP status code. Undefined if successful int
message Error message. Undefined if successful string

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.

Name Description Type max byte Required
id Primary ID of the voucher Integer Yes
programId Primary key of the program owning the offer Integer   Yes
programName Name of the program String   Yes
code Actual voucher code String 256 Yes*
updateDate Last update date in UNIX Epoch time milliseconds or ISO8601 depending on your dateOutputFormat Integer   Yes
startDate Start date in UNIX Epoch time milliseconds or ISO8601 depending on your dateOutputFormat Integer   Yes
endDate End date in UNIX Epoch time milliseconds or ISO8601 depending on your dateOutputFormat Integer   Yes
title Title of the offer String 32 Yes
shortDescription Short description of the offer String 100 No
description Long description of the offer String 65535 No
voucherTypeId Primary key of the type. See table for specification Integer   Yes
defaultTrackUri Default tracker link. Use this to link to the advertiser. String   Yes
siteSpecific Set to True if the offer is only available to your site. Boolean   Yes
landingUrl If the offer has a specific landing page, its URL will be presented here. It is also amended to defaultTrackUri. String 2048 No

*Code is only required for voucherTypeId=1.


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.

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.

Module Error code HTTP code HTTP status Description
Open API1 400 Bad Request Missing token
Open API 2 403 Forbidden Invalid token
Open API 3 404 Not Found Invalid API version
Open API 4 404 Not Found Invalid module version
Open API 5 500 Internal Server Error Service not responding
Open API 6 404 Not Found Missing version
Open API 7 404 Not Found Missing module
Create voucher 101 400 Bad Request Invalid voucher information (e.g. too long title)
Create voucher 102 400 Bad Request No access to program
Create voucher 103 400 Bad Request No connection between program and site

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

The most common HTTP errors are:

HTTP code HTTP status Description
400 Bad Request Invalid XML, Json or date format
404 Not Found The URL does not exist
405 Method Not Allowed Invalid HTTP method (e.g. GET instead of POST)
406 Not Acceptable Requesting invalid content type (e.g text/plain instead of application/xml)
415 Unsupported Media Type Sending invalid content type
500 Internal Server Error Service down