Vouchers API

Dynamically distribute your voucher codes to Tradedoubler publishers.

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

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

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:

Name Description Type Max byte Required
title Title of the offer String 32 Yes
programId Primary key of the program owning the offer Integer   Yes
voucherTypeId Primary key of the type. See table for specification Integer   Yes
code Actual voucher code String 256 Yes*
shortDescription Short description of the offer String 100 Yes
description Long description of the offer String 65535 Yes
startDate Start date in UNIX Epoch time milliseconds Integer   Yes
endDate End date in UNIX Epoch time milliseconds. May not be more than six months in the future. Integer   Yes
sourceId Set to your internal identifier. Used to edit existing vouchers. String   No
siteIds If you send site IDs to the API, only these sites will access the offer. Integer/array**   No
landingUrl Landing URL of the offer. String 2048 No
publishStartDate Publication date of the voucher. This is usually set to a few days before the startDate so publishers have time to set up the offer. Integer   No
publishEndDate Publication end date of the voucher. Integer   No
publisherInformation Information intended for the publisher (not end user). You can add information on how the voucher should be presented etc. String   No
discountAmount The amount of discount the voucher gives. This field is required for voucher type discount. Float   Yes*
isPercentage Set to true if discountAmount is a percentage. String Yes*
languageId Setting a language on a voucher makes it possible for publishers to filter by language. Useful for multilingual countries. Use the ISO 639-1 code, for example en for English or sv for Swedish. String No

*Only required in some cases.

**If posting XML, use one or more siteId elements. If posting JSON, send an array with one or more values.

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 voucher code. With this type it is mandatory to provide a voucher code.
2 Discount General discount without a voucher code. With this type it is mandatory to provide the 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.

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.

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 returns in ISO8601 format String No
programId Primary key of the program owning the voucher 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 site specific voucher codes. Boolean No
pageSize Number of items to return. Defaults to 1000 Integer No
page Page number given you get more items than pageSize. Defaults to 0 Integer No
random Enter a seed to get a specific randomized order of your result Integer 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 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:

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

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}
{voucher_id} is the primary key of the voucher to delete.

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.

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