Vouchers API

Overview

The Vouchers API allows you to manage your voucher codes through a REST API. By using the API, you can systematically send vouchers to Tradedoubler whenever you create them in your own internal system, reducing manual workload and getting your data out to your network of publishers instantly.

Other key benefits or using the Vouchers API:

• Dynamically distribute voucher code information.
• Control which vouchers end up on publisher sites.
• Give specific sites exclusive vouchers.
• Deleting a voucher will delete it from publisher sites.

Don´t have a publisher program with Tradedoubler? Contact us

This documentation is intended for advertisers. If you are a publisher, please go to the publisher documentation.

Authentication

In order to access the Vouchers API, you need an account with Tradedoubler. Once you have an account, you can pick up your unique token by logging on and going to "Settings" > "Management" > "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 cross-domain security issues, even when posting or deleting!

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.

Create voucher service

The syntax to create a voucher is:

HTTPS POST https://api.tradedoubler.com/1.0/vouchers?token={token}

Post data

You can send your data as XML (application/xml) or JSON (application/json). Depending of which media type you specify, the API will expect that data.

This is the data to send to the API:

Voucher type ID

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

Example post data

XML data

This is an example of valid XML data to send to the Vouchers API:

<voucher>
	<programId>15603</programId>
	<code>XS51F9</code>
	<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>
	<siteId>222</siteId>
	<siteId>333</siteId>
	<landingUrl>http://www.example.com/product?id=123</landingUrl>
	<discountAmount>10</discountAmount>
	<isPercentage>true</isPercentage>
</voucher>

JSON data

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

{
	"programId": 15603,
	"code": "XS51F9",
	"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,
	"siteIds" : [222,333],
	"landingUrl": "http://www.advertiser.co.uk/affiliate-landing",
	"discountAmount": 10,
	"isPercentage": true,
}

Create response

If voucher creation is successful, you will receive the primary key as a response. In these examples 123 represents the primary key:

XML:

  <long>123</long>

Json:

  [123]

See error management for details on error messages.

Editing vouchers

Edit existing voucher simply by setting sourceId to what you specified when creating the voucher. If you did not specify a sourceId when creating the voucher, you can use Tradedoubler's identifier as sourceId insted. You can find which sourceId a voucher has by using the get voucher service.

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 for practical examples

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 extension, 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 https://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 https://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 https://api.tradedoubler.com/1.0/vouchers.xml;voucherTypeId=2;voucherTypeId=5;programId=50000?token={token}&jsonp=myCallback

Get all vouchers connected to site ID 111, 222 or 333 in XML:

HTTP[S] GET https://api.tradedoubler.com/1.0/vouchers.xml;siteId=111;siteId=222;siteId=333?token={token}

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

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

Example responses

XML response:

<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 data

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
    }
  });
}

Delete voucher service

This is the delete voucher syntax:

HTTPS DELETE https://api.tradedoubler.com/1.0/vouchers/{voucher_id}?token={token}

Delete response

If the deletion is successful the API returns a HTTP No Response 204. Otherwise the API will return HTTP Error 400 "Bad request"

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: