Products API

Programmatically distribute your product database to Tradedoubler publishers.

Overview

The Products API lets you distribute your product database through a REST API. As soon as you push product data to Tradedoubler, it becomes available to your publishers.

The Products API allows you as an advertiser to:

  • Programmatically push product data to publishers.
  • Connect with technically advanced publishers.
  • Get your products listed on price comparison sites.
  • Let 3rd party developers create innovative content.
  • Control your product data in real time.

Do not have an affiliate program with Tradedoubler? Contact us


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

Demo website

This demo website is based on the Tradedoubler Products API. Publishers can easily build things like these with your product data if you just provide your data.

Authentication

In order to access the Products 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 Products API is under the system "PRODUCTS".

Examples in this document use {token} as placeholder. You should replace this with 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 service

The create service is the main service for you as an advertiser. Use it to add new or update existing products in Tradedoubler's API.

The syntax for the service is:

HTTPS POST https://api.tradedoubler.com/1.0/products;fid={feedId}?token={token}

There are two required keys in the request:

Name Description Type
token Your unique token, identifying you as an advertiser. String
fid Product feed primary key. This is supplied by your Tradedoubler contact person. Integer

Request headers

When posting your request, you need to tell the service what type of content you are posting. The service can read JSON and XML. Use application/json if you are posting JSON and application/xml if you are sending XML.

We only accept UTF-8 as character set, so please make sure that you use that and specify it in the Content-Type header.

JSON: Content-Type: application/json; charset=utf-8

XML: Content-Type: application/xml; charset=utf-8

Post data

This table shows all data you can send to Tradedoubler. Even though not all are required we encourage you to send as much data as possible since it helps publishers create more powerful applications.

Many publishers rely on a global identifier such as an international article number (EAN) so please try to provide at least one. Tradedoubler uses such identifiers to group products.

If you do not provide global identifiers, your products become less visible in the API.
Name Description Type Required
categories Parent of categories attributes (id, name, tdCategoryName). N/A Yes
id ID of the Tradedoubler category that the product is mapped to. String Yes*
name Advertiser category name. String Yes*
tdCategoryName Name of the Tradedoubler category that the product is mapped to. String No
description A long description of the product. String Yes
name Title of the product. String Yes
price Price of the product in the currency of your affiliate program. Use no or two decimals and dot as decimal mark. For example "199" or 149.90". Float Yes
productImage Parent of productImage attributes (url, width, height). N/A Yes
url A URL to an image of the product. Image size is important, around 500x300 is good - not too small and not high resolution. Try to also add width and height to the image. String Yes
width Width of the product image in pixels. Integer No
height Height of the product image in pixels. Integer No
productUrl Your URL to the product page. This is used to deep link to your product which significantly increases the conversion rate. String Yes
sourceProductId Your internal ID for the product. This is used to determine if you are posting a new product or updating an existing one. String Yes
availability Information on the availability of the product. (e.g. "In stock", "Available 2012-12-24"). String No
brand Brand of the product (e.g. "Weetos"). String No
condition Condition of the product (e.g. "Used" or "New"). String No
deliveryTime The amount of time it takes to get the product delivered. String No
identifiers Parent of identifiers attributes (ean, sku, upc, isbn, mpn). N/A No
ean International article number of the product. This is extremely useful for both publishers and Tradedoubler. Publishers use it to systematically find out which product it is and Tradedoubler use it to group products. Integer No
sku Stock-keeping unit of the product. Can also be used by publishers and Tradedoubler as a product identifier. String No
upc Universal Product Code. Can also be used by publishers and Tradedoubler as a product identifier. String No
isbn International Standard Book Number. Can also be used by publishers and Tradedoubler as a product identifier. String No
mpn Manufacturer part number. Can also be used by publishers and Tradedoubler as a product identifier. String No
inStock Number of items the advertiser has in stock as an integer. Integer No
manufacturer Manufacturer of the product (e.g. "Cole's Corn"). String No
model The product's model (e.g. "Chocolate Cereal"). String No
promoText Promotional text for the product. String No
shippingCost Cost of getting the product delivered (e.g. "Free", "11.95"). String No
shortDescription Description of the product in fewer words. String No
size Size/dimonsions of the product (e.g. "200x120x40mm"). String No
techSpecs Technical specification of the product. String No
warranty Warranty information about the product. String No
weight Weight of the product. For example "25kg" String No
fields If you have any information about your product that does not fit any of the attributes above, you place it in fields. You can provide as many fields as you like. N/A No
name Name of the custom attribute you wish to add. String No
value Value of the custom attribute. String No

*Either id or name is required.

No delay! We strongly suggest that you provide Tradedoubler's category ID to reduce category mapping time. Read more on categorization.

Note that we only accept Unicode characters that XML processors must accept as per W3 standards (see https://www.w3.org/TR/REC-xml/#charsets). The allowed character range is therefore:

  • U+0009
  • U+000A
  • U+0020 - U+D7FF
  • U+E000 - U+FFFD
  • U+10000 - U+10FFFF

JSON post data example

This is an example of how to build the data in the JSON format:

{
  "products":[
    {
      "sourceProductId":"12-113-4917",
      "name":"Tradedoubler Concert Ukulele",
      "description":"This Concert Size Ukulele is part of the exciting range of premium-uniquely featured high grade series Ukuleles designed for the most professional and aspiring of musicians.",
      "productUrl":"http://www.tradedoubler.com/products/12-113-4917/",
      "productImage":{
        "url":"http://www.tradedoubler.com/products/12-113-4917/images/main.jpg",
        "width":500,
        "height":300
      },
      "price":225,
      "categories":[
        {
          "name":"Ukuleles",
          "id":160
        }
      ],
      "fields":[
        {
          "name":"Type",
          "value":"Ukulele"
        },
        {
          "name":"Colour",
          "value":"Brown"
        }
      ],
      "shippingCost":"9",
      "shortDescription":"High grade series Ukuleles designed for the most professional and aspiring of musicians.",
      "promoText":"Learn to play the Ukulele like a professional!",
      "warranty":"Two-year warranty",
      "inStock":34,
      "availability":"In stock",
      "deliveryTime":"5 business days",
      "condition":"New",
      "weight":"580g",
      "size":"50x20x8cm",
      "model":"Cedar Concert",
      "brand":"Tradedoubler",
      "manufacturer":"Tradedoubler",
      "techSpecs":"4-string mahogany neck, 432 mm scale, rosewood fretboard, 18 brass frets, nut width: 44,5 mm, geared tuners.",
      "ean":"810486016247",
      "upc":"4180610",
      "isbn":"9789113043722",
      "mpn":"9789113043722",
      "sku":"12-113-4917"
    }
  ]
}

XML post data example

This is the same product as above but formatted as XML.

<products xmlns="urn:com:tradedoubler:pf:model:xml:input" xmlns:cm="urn:com:tradedoubler:pf:model:xml:common" version="3.0">
  <product sourceProductId="12-113-4917">
    <cm:name>Tradedoubler Concert Ukulele</cm:name>
    <cm:description>This Concert Size Ukulele is part of the exciting range of premium-uniquely featured high grade series Ukuleles designed for the most professional and aspiring of musicians.</cm:description>
    <cm:productUrl>http://www.tradedoubler.com/products/12-113-4917/</cm:productUrl>
    <cm:productImage>http://www.tradedoubler.com/products/12-113-4917/images/main.jpg</cm:productImage>
    <cm:price>225</cm:price>
    <cm:categories>
      <cm:category name="Guitars" id="162"/>
    </cm:categories>
    <cm:fields>
      <cm:field name="Type">Ukulele</cm:field>
      <cm:field name="Colour">Brown</cm:field>
    </cm:fields>
    <cm:shippingCost>9</cm:shippingCost>
    <cm:shortDescription>High grade series Ukuleles designed for the most professional and aspiring of musicians.</cm:shortDescription>
    <cm:promoText>Learn to play the Ukulele like a professional!</cm:promoText>
    <cm:warranty>Two-year warranty</cm:warranty>
    <cm:inStock>34</cm:inStock>
    <cm:availability>In stock</cm:availability>
    <cm:deliveryTime>5 business days</cm:deliveryTime>
    <cm:condition>New</cm:condition>
    <cm:weight>580g</cm:weight>
    <cm:size>50x20x8cm</cm:size>
    <cm:model>Cedar Concert</cm:model>
    <cm:brand>Tradedoubler</cm:brand>
    <cm:manufacturer>Tradedoubler</cm:manufacturer>
    <cm:techSpecs>4-string mahogany neck, 432 mm scale, rosewood fretboard, 18 brass frets, nut width: 44,5 mm, geared tuners.</cm:techSpecs>
    <cm:ean>810486016247</cm:ean>
    <cm:upc>4180610</cm:upc>
    <cm:isbn>9789113043722</cm:isbn>
    <cm:mpn>9789113043722</cm:mpn>
    <cm:sku>12-113-4917</cm:sku>
  </product>
</products>

XML schemas

XSD files for the input format are available here:

Name File
Common format ProductsFeedCommon_v3_0.xsd
Input format ProductsFeedInput_v3_0.xsd
Old format? If you have worked with Tradedoubler's old product feed solution, you can use this XSL document to transform the old format to version 3.

Updating products

Replacing entire feed

You may wish to perform a bulk update for an existing feed; you can do this using the replace mode. This is much more efficient than deleting all products and creating new entries, and also preserves/updates the price history.

Using the replace mode will replace all existing products with the new entries. Take this example:

  • You currently have product A, B and C in your feed.
  • You use the replace mode and send in product A, B and D.
  • The feed will now contain product A, B and D.
  • Price history for product A and B will be updated if the price had changed.


This is the syntax for updating products:

HTTPS POST http://api.tradedoubler.com/1.0/products;fid={feedId};mode=replace?token={token}

Product data should be sent as described in the create service post data section above.


Updating specific products

If you want to update some existing products in your feed and retain the other products, you can use the create service. We match all posted product's sourceProductId against all products in that particular feedId. If the sourceProductId already exists, we update the product. If it does not exist, we create a new product. Products that exist in the feed but are not mentioned in the new create request will be left untouched.


Note: The create service should not be used for updating all products - the replace service should be used instead.

Delete service

When a product is deleted from your product catalogue, you need to tell Tradedoubler about it.

This is the syntax for deleting products:

HTTPS DELETE http://api.tradedoubler.com/1.0/products;fid={feedId};spId={sourceProductId}[;deleteAll={true}]?token={token}

Query keys

These are the available query keys, when using the delete service:

Name Description Type Mandatory Multiple
token Your unique token, identifying you as an advertiser. String yes no
fid The ID of the feed containing the product(s) to be deleted. long yes no
spId One or more of your internal product identifiers. When the products were created, you sent these as sourceProductId. String yes* yes
deleteAll If you want to delete all products from your feed, you can set deleteAll to true. Boolean no no

*spId is only mandatory if you are not deleting all products, using deleteAll.

If you want to delete multiple products at once, use either one key for each value spId=myProdId-111;spId=myProdId-222 or comma separate values spId=myProdId-111,myProdId-222

It is also possible to delete all products from a feed, simply by removing the spId key and setting deleteAll to true.

No stock? Do not delete a product when it is out of stock. Most publishers want to find it anyway. Make good use of availability and inStock instead. Only post delete requests for products that are permanently out of your product catalogue.

Examples requests

Delete product ID "myProd-111" and "myProd-222" from feed ID 33333:

HTTPS DELETE https://api.tradedoubler.com/1.0/products;fid=33333;spId=myProd-111,myProd-222?token={token}

Delete all products from feed ID 33333:

HTTPS DELETE https://api.tradedoubler.com/1.0/products;fid=33333;deleteAll=true?token={token}

Response

If a product creation/update/deletion is successful, you will receive a response without errors.

JSON:

errors[]

XML:

<Response xmlns="http://api.tradedoubler.com/1.0/products">
  <errors/>
</Response>

However if the creation/update/deletion of one or more products failed, we will try to explain why. This is an example of the error reported when a product is missing its description.

JSON:

{
  "errors":[
    {
      "code":"PF_240",
      "sourceProductId":"myProdId-111",
      "message":"Value missing : description"
    }
  ]
}

XML:

<Response xmlns="http://api.tradedoubler.com/1.0/products">
   <errors>
      <e>
         <code>PF_240</code>
         <message>Value missing : description</message>
         <sourceProductId>myProdId-111</sourceProductId>
      </e>
   </errors>
</Response>
Read more about error management and see which errors that can occur when using the API below.

Search service

This is the main search service of Products API. Use it to query the API for products.

The syntax of the search service is:

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

Query keys

You can add a query to your request if you want to filter the results. All data may not be available on products.

Name Description Type Multiple
token Your unique token, identifying you. Required to provide. String No
q Generic keyword search. Matches intelligently against title and description. String Yes
fid Feed ID. Required to provide. Integer Yes
currency Matches against the currency of products. String No
minPrice Search for products with a minimum price. Float No
maxPrice Search for products with a maximum price. Float No
minUpdateDate Search for products updated after a certian point in time. Date No
maxUpdateDate Search for products updated before a certian point in time. Date No
tdCategoryId Matches against the Tradedoubler category ID Integer Yes
category Matches against the advertiser category name String Yes
brand Matches against the brand of products String Yes
spId Matches against the advertiser product ID. String Yes
tdId Matches against the Tradedoubler ID of products String Yes
ean Matches against the european article number of products String Yes
mpn Matches against the manufacturer part number of products String Yes
sku Matches against the stock keeping unit of products String Yes
upc Matches against the universal part number of products String Yes
isbn Matches against the international standard book number of products String Yes
language Matches against the language of the feed containing products String No
field Search among custom information on a product. For example field=colour%3Dblack String No
orderBy Set the order in which products are returned. Choose between priceAsc, priceDesc, modificationDateAsc and modificationDateDesc. String No
page Which page of result to return, given limit and pageSize is set. Integer No
pageSize The maximum number of items to return. Integer No
limit Global limit of the returned document. Set to pageSize*page+pageSize in order to use pagination. Integer No
groupOffersByProduct Set to true if you want the same product from different advertisers to be grouped. Boolean No
priceHistory Set to true to enable price history which gives you a list of previous prices for products. Boolean No
dateOutputFormat Set to iso8601 to use ISO8601 dates, otherwise dates will be output as unix time in milliseconds. String No
availability Matches against the availability of products String Yes
minInStock Miminum number of products in stock. Integer No
maxInStock Maximum number of products in stock. Integer No
condition Matches against the condition of products String Yes
model Matches against the model of products String Yes
manufacturer Matches against the manufacturer of products String Yes
shippingCost Matches against the shipping cost of products String Yes
promoText Matches against the promoText of products String Yes
warranty Matches against the warranty of products String Yes
deliveryTime Matches against the delivery time of products String Yes
weight Matches against the weight of products String Yes
size Matches against the size of products String Yes
techSpec Matches against the technical specification of products String Yes
pretty Set to true for nice line breaks in the output. Boolean No
jsonp If you are requesting JSON, you can define a callback name. The API will return a Javascript document with the result as an array in a function named as the callback. String No
Manifold: If you want to enter multiple values for a key, use either one key for each value brands=Cheerios&brands=Weetos or comma separate values brands=Cheerios,Weetos. Make sure that the key supports multiple values first.
Encoding: If you are searching categories and your search term includes a comma (,) you need to double encode the comma to prevent the search term being split into a list of items. For example, searching for category=Cheerios%252CWeetos will search for the single term "Cheerios,Weetos". Not double encoding the comma will result in two search terms being used - "Cheerios" and "Weetos".

Example requests

Get all available products in JSON:

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

Get products matching "laptop" in XML:

HTTP[S] GET http://api.tradedoubler.com/1.0/products.xml;q=laptop?token={token}

Get Weetos products costing at least £200 with price history enabled:

HTTP[S] GET http://api.tradedoubler.com/1.0/products;brands=Weetos;priceHistory=true;pricemin=200?token={token}

Get five football related products in a pretty JSON format with grouping enabled:

HTTP[S] GET http://api.tradedoubler.com/1.0/products;groupoffersbyproduct=true;pretty=true;limit=5;q=football?token={token}

Response expectations

As a response to your request, you can expect some of the following data. Please note that not all data is present for all products.

Name Description Type Required
categories Parent of categories attributes (id, name, tdCategoryName). N/A Yes
id ID of the Tradedoubler category that the product is mapped to. String Yes*
name Advertiser category name. String Yes*
tdCategoryName Name of the Tradedoubler category that the product is mapped to. String No
description A long description of the product. String Yes
feedId Primary key of the feed owning the product. Integer Yes
groupingId The identifier Tradedoubler use to group this product. String Yes
id Tradedoubler's internal identifier of the product. May be used as GUID. String Yes
modified Date of the last modification in ISO-8601 or unix time depending on the dateOutputFormat parameter. For example 2012-12-24T15:00+0100 or 1356357600000 Date Yes
name Title of the product. String Yes
price Price of the product. Currency is picked up from your affiliate program. Float Yes
priceHistory A list of all price changes during the life of the product. Each entry will detail the price, currency and date changed. Array Yes
productImage Parent of productImage attributes (url, width, height). N/A Yes
url A URL to an image of the product. String Yes
width Width of the product image in pixels. Integer No
height Height of the product image in pixels. Integer No
productUrl URL to the product. Use this to link to the product and earn commission. If publisher token is used, the product URL is prefixed with Tradedoubler's tracker URL. String Yes
programName Name of the program of the feed this product belongs to. String Yes
sourceProductId Your identifier of the product. String Yes
availability Information on the availablity of the product. String No
brand Brand of the product. For example "Apple". String No
condition Condition of the product. For example used or new. String No
deliveryTime The amount of time it takes to get the product delivered. String No
identifiers Parent of identifiers attributes (ean, sku, upc, isbn, mpn). N/A No
ean International article number of the product. Used for grouping and can be used as product identifier. Integer No
sku Stock-keeping unit of the product. Used for grouping and can be used as product identifier. String No
upc Universal Product Code. Used for grouping and can be used as product identifier. String No
isbn International Standard Book Number. Used for grouping and can be used as product identifier. String No
mpn Manufacturer part number. Used for grouping and can be used as product identifier. String No
inStock Number of items you have in stock. Integer No
language ISO 639-1 code of the language to use in the response. For example en for English or sv for Swedish. String No
manufacturer Manufacturer of the product. For example "Samsung" String No
model The product's model. For example "iPhone" String No
programLogo Url to the logo of the program of the feed this product belongs to. String No
promoText Promotional text of the product String No
shippingCost Cost of getting the product delivered. For example "Free" or "11.95". String No
shortDescription Description of the product in fewer words. String No
size Size of the product. String No
techSpecs Technical specification of the product. String No
warranty Warranty information about the product String No
weight Weight of the product. String No
fields Additional information about the product that does not fit any of the attributes above. N/A No
name Name of the custom attribute. String No
value Value of the custom attribute. String No
Name Description Type Required
name Title of the product String Yes
description A long description of the product. String Yes
productImage.url A URL to an image of the product. String Yes
productImage.width programmatically Integer No
productImage.height Height of the product image in pixels. Integer No
categories Categories of the product. tdCategoryName is Tradedoubler's category name, id is Tradedoubler's category ID and name is the your category name. String Yes*
feedId Primary key of the feed owning the product. Integer Yes
language ISO 639-1 code of the language to use in the response. For example en for English or sv for Swedish. String No
productUrl URL to the product. Use this to link to the product and earn commission. If publisher token is used, the product URL is prefixed with Tradedoubler's tracker URL. String Yes
programName Name of the program of the feed this product belongs to. String Yes
programLogo Url to the logo of the program of the feed this product belongs to. String No
priceHistory A list of all price changes during the life of the product. Each entry will detail the price, currency and date changed. Array Yes
Price Price of the product. Currency is picked up from your affiliate program. Float Yes
sourceProductId Your identifier of the product. String Yes
modified Date of the last modification in ISO-8601 or unix time depending on the dateOutputFormat parameter. For example 2012-12-24T15:00+0100 or 1356357600000 Date Yes
id Tradedoubler's internal identifier of the product. May be used as GUID. String Yes
groupingId The identifier Tradedoubler use to group this product. String Yes
ean International article number of the product. Used for grouping and can be used as product identifier. Integer No
sku Stock-keeping unit of the product. Used for grouping and can be used as product identifier. String No
upc Universal Product Code. Used for grouping and can be used as product identifier. String No
isbn International Standard Book Number. Used for grouping and can be used as product identifier. String No
mpn Manufacturer part number. Used for grouping and can be used as product identifier. String No
availability Information on the availablity of the product. String No
inStock Number of items you have in stock. Integer No
condition Condition of the product. For example used or new. String No
brand Brand of the product. For example "Apple". String No
model The product's model. For example "iPhone" String No
manufacturer Manufacturer of the product. For example "Samsung" String No
shippingCost Cost of getting the product delivered. For example "Free" or "11.95". String No
shortDescription Description of the product in fewer words. String No
promoText Promotional text of the product String No
warranty Warranty information about the product String No
deliveryTime The amount of time it takes to get the product delivered. String No
weight Weight of the product. String No
size Size of the product. String No
techSpecs Technical specification of the product. String No
fields Advertisers can add any other information to a product. These are presented in "fields". See examples below for details. String No

*Either tdCategoryName or name is always present.

Note: Only information set as "required" above is present on all products. Other types of information is not mandatory for advertisers to provide.

JSON response

This is an example of a JSON response. It contains one product with lots of information.

{
  "productHeader" : {
    "totalHits" : 1
  },
  "products" : [ {
    "name" : "Symantec pcAnywhere Host & Remote - (versie 12.5 ) - volledig pakket - 5 gebruikers - CD - Linux, Win - International",
    "productImage" : {
      "url" : "http://snpi.dell.com/snp/images/products/mlrg/nl-nl~A6854908/A6854908.jpg"
    },
    "language" : "sv",
    "description" : "Symantec pcAnywhere is een uitgebreide, veilige oplossing voor remote besturing en beheer die is voorzien van functies voor het doorgeven van bestanden, zodat helpdesk- en supportkwesties snel kunnen worden opgelost, ook over meerdere platforms. De invitation-functie voor gateways en hosts is een oplossing voor typische connectiviteitsproblemen waarmee organisaties en het MKB mee te maken krijgt die meerdere remote apparaten ondersteunen. Doordat de gateway-functie de detectie van en de veilige verbinding met meerdere apparaten achter een firewall of NAT (Network Address Translation) in real time mogelijk maakt, kunnen helpdeskmedewerkers sessies met eindgebruikers initiëren,",
    "identifiers" : {
      "sku" : "A6854908"
    },
    "fields" : [ {
      "name" : "ManufacturerID",
      "value" : "14530209"
    }, {
      "name" : "HomeDelivery",
      "value" : "Yes"
    }, {
      "name" : "StaticSKU",
      "value" : "A6854908nlnl"
    }, {
      "name" : "VendorCode",
      "value" : "93"
    }, {
      "name" : "CategoryID",
      "value" : "5243"
    }, {
      "name" : "VendorName",
      "value" : "Symantec Corporation"
    }, {
      "name" : "Channel",
      "value" : "bsd"
    }, {
      "name" : "ArticleID",
      "value" : "14530209"
    }, {
      "name" : "productLink",
      "value" : "http://accessories.euro.dell.com/sna/productdetail.aspx?c=nl&l=nl&s=bsd&cs=nlbsdt1&sku=A6854908"
    } ],
    "offers" : [ {
      "feedId" : 8976,
      "productUrl" : "http://www.rf.nl/dellspider/redir.asp?c=nl&l=nl&a=bsd&ProductID=A6854908&redir=http%3A%2F%2Flt%2Edell%2Ecom%2Flt%2Flt%2Easpx%3FCID%3D6511%26LID%3D167791%26DGC%3DAF%26DGSeg%3DBSD%26ACD%3D[td_guid]%26AID%3D[td_affiliate_id]%26DURL%3DDestinationURL",
      "priceHistory" : [ {
        "price" : {
          "value" : "617.28",
          "currency" : "EUR"
        },
        "date" : 1378557168050
      } ],
      "modified" : 1381505376751,
      "availability" : "In Stock",
      "deliveryTime" : "Gebruikelijke verzending in: + 3 weken",
      "condition" : "New",
      "shippingCost" : "Kostenlos",
      "sourceProductId" : "A6854908nlnl",
      "programName" : "Wanten testzzzzzzzzzz",
      "id" : "519de2b6e4b00d36c4c7e7c0"
    } ],
    "categories" : [ {
      "name" : "Software en downloads - Zakelijk & kantoor"
    } ]
  } ]
}

JSONP

If you defined the jsonp key in your query (for example jsonp=myCallbackFunction), the API will return a Javascript document with the result as an array in a function named as the callback:

function myCallbackFunction(result, statusCode, message)

JSONP callback function argument definitions:

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

If you did not define the jsonp key, the API will return actual JSON with Content-Type: application/json.

JSONP, really? Well, api.tradedoubler.com is CORS enabled, so you may not want to use JSONP at all. Learn more.

XML response

This is the same product as above, formatted as XML:

<result version="3.0" xmlns:ns2="urn:com:tradedoubler:pf:model:xml:common" xmlns="urn:com:tradedoubler:pf:model:xml:output">
    <productHeader>
        <totalHits>1</totalHits>
    </productHeader>
    <products>
        <product language="sv">
            <ns2:name>Symantec pcAnywhere Host & Remote - (versie 12.5 ) - volledig pakket - 5 gebruikers - CD - Linux, Win - International</ns2:name>
            <ns2:description>Symantec pcAnywhere is een uitgebreide, veilige oplossing voor remote besturing en beheer die is voorzien van functies voor het doorgeven van bestanden, zodat helpdesk- en supportkwesties snel kunnen worden opgelost, ook over meerdere platforms. De invitation-functie voor gateways en hosts is een oplossing voor typische connectiviteitsproblemen waarmee organisaties en het MKB mee te maken krijgt die meerdere remote apparaten ondersteunen. Doordat de gateway-functie de detectie van en de veilige verbinding met meerdere apparaten achter een firewall of NAT (Network Address Translation) in real time mogelijk maakt, kunnen helpdeskmedewerkers sessies met eindgebruikers initiëren,</ns2:description>
            <ns2:productImage>http://snpi.dell.com/snp/images/products/mlrg/nl-nl~A6854908/A6854908.jpg</ns2:productImage>
            <ns2:categories>
                <ns2:category name="Software en downloads - Zakelijk &amp; kantoor"/>
            </ns2:categories>
            <ns2:fields>
                <ns2:field name="ManufacturerID">14530209</ns2:field>
                <ns2:field name="HomeDelivery">Yes</ns2:field>
                <ns2:field name="StaticSKU">A6854908nlnl</ns2:field>
                <ns2:field name="VendorCode">93</ns2:field>
                <ns2:field name="CategoryID">5243</ns2:field>
                <ns2:field name="VendorName">Symantec Corporation</ns2:field>
                <ns2:field name="Channel">bsd</ns2:field>
                <ns2:field name="ArticleID">14530209</ns2:field>
                <ns2:field name="productLink">http://accessories.euro.dell.com/sna/productdetail.aspx?c=nl&l=nl&s=bsd&cs=nlbsdt1&sku=A6854908</ns2:field>
            </ns2:fields>
            <ns2:sku>A6854908</ns2:sku>
            <offers>
                <offer dateFormat="epoch" modifiedDate="1381505376751" sourceProductId="A6854908nlnl" id="519de2b6e4b00d36c4c7e7c0">
                    <ns2:feedId>8976</ns2:feedId>
                    <ns2:productUrl>http://www.rf.nl/dellspider/redir.asp?c=nl&l=nl&a=bsd&ProductID=A6854908&redir=http%3A%2F%2Flt%2Edell%2Ecom%2Flt%2Flt%2Easpx%3FCID%3D6511%26LID%3D167791%26DGC%3DAF%26DGSeg%3DBSD%26ACD%3D[td_guid]%26AID%3D[td_affiliate_id]%26DURL%3DDestinationURL</ns2:productUrl>
                    <ns2:programName>Wanten testzzzzzzzzzz</ns2:programName>
                    <priceHistory>
                        <ns2:price dateFormat="epoch" date="1378557168050" currency="EUR">617.28</ns2:price>
                    </priceHistory>
                    <ns2:availability>In Stock</ns2:availability>
                    <ns2:deliveryTime>Gebruikelijke verzending in: + 3 weken</ns2:deliveryTime>
                    <ns2:condition>New</ns2:condition>
                    <ns2:shippingCost>Kostenlos</ns2:shippingCost>
                </offer>
            </offers>
        </product>
    </products>
</result>

To get your response as XML, add xml as extension products.xml.

XML schemas

XSD files for the output format are available here:

Name File
Common format ProductsFeedCommon_v3_0.xsd
Output format ProductsFeedOutput_v3_0.xsd

CSV export

You may wish to export the results in CSV rather than JSON or XML. To do so, you need to modify the search service syntax as follows:

HTTP[S] GET http://api.tradedoubler.com/1.0/products[.xml|.json|empty][format=csv][csvSeparators][csvEmbrace][csvFlattenFields][query keys]?token={token}
Name Description Expected value
Format Informs the service that a CSV export should be performed. csv
csvSeparators Defines the character used as a field separator. There are three levels within the Products API - categories, category and attribute. You must define the separator to be used for each in that order (see below for more information). The value must be URL encoded. The default value is ,;: Three URL encoded characters (e.g. ;||)
csvEmbrace Defines the character used to embrace each field (sometimes called text qualifier). The value must be URL encoded. URL encoded characters (e.g. ")
csvFlattenFields Defines whether fields should be flattened or not. The default value is false. Boolean (e.g. True or False)

CSV separators

Take this example of product data:

...
"categories" : [
	{
	  "name" : "Electronics",
	  "tdCategoryName" : "Electronics",
	  "id" : 40
	},
	{
	  "name" : "Projectors",
	  "tdCategoryName" : "Projectors",
	  "id" : 62
	}
]
...

The above extract shows a product with two categories (Electronics and Projectors). The separators are as follows:

  • Categories - On line seven, after the closing } a comma is used to separate the first value of 'categories' from the second.
  • Category - Within each category there are multiple attributes and values. Each attribute is seprated by a comma (e.g. at the end of lines four and five).
  • Attribute - Attibutes are separated from their value with a semi-colon (e.g. "attribute" : "value").

Example requests

Use " as the embrace character and use |:; as the separators and flatten the fields:

HTTP[S] GET http://api.tradedoubler.com/1.0/products;format=csv;fid=9612;csvSeparators=%7C%3A%3B;csvEmbrace=%22;csvFlattenFields=true?token={token}

Use " as the embrace character and ,;: as the separators and do not flatten the fields (these are the default settings so they do not need to be listed) :

HTTP[S] GET http://api.tradedoubler.com/1.0/products;format=csv;fid=9612;?token={token}

Limitations

Any search request is limited to a maximum of 1,000 products. That means that adding page=2;pageSize=1000 will not get any results since the cap has already been reached at page one.

Unlimited service

In addition to the search service, you can use the unlimited service to get all of your raw product data from a specific feed.

This service is intended to be used by technically advanced users who wish to save the data to their own database, and process it on their own.

Download Limit

In order to prevent excessive downloading of unchanged Unlimited files you are allowed to download each version of a file 3 times within a 24-hour window. If this threshold is exceeded the service will respond with http 429 – Too Many Requests, instead of providing the file. Here is a sample response for the same :

“code”: “429”,

“message”: “Request Quota exceeded. Feed has not been updated recently”

When a new version of a file is published you are immediately granted download permission again. You can use the endpoint Unlimited Last Updated service as described below to get the last updated time of a specific feed.

When an unlimited file is requested for the first time there is an initial grace period of 5 days from the download limit. During this period the limit does not apply so that you can experiment and ensure proper functionality of the integration.


The syntax of the unlimited service is:

HTTP[S] GET http://api.tradedoubler.com/1.0/productsUnlimited[.xml|.json|empty];fid={feedId}?token={token}[&jsonp=myCallback]

Query keys

These are the query keys available to unlimited requests:

Name Description Type Required
token Your unique token, identifying you as an advertiser. String Yes
fid Primary key of the feed you are requesting. Integer Yes
page Which page of the result to return, given pageSize has been set. Integer No*
pageSize The maximum number of items to return per page. Integer/td> No*
pretty Set to true for nice line breaks in the output. Boolean No
* If either page or pageSize is specified then the other becomes mandatory.
Be aware! Unlimited responses can contain millions of products, causing browsers to crash.

Example requests

Get all products from feed ID 123 as JSON:

HTTP[S] GET http://api.tradedoubler.com/1.0/productsUnlimited;fid=123?token={token}

Unlimited feed last updated service

You can use the unlimited feed last updated service to get the last updated time for a specific feed.

It would be ideal to use this service before the unlimited search service. If the feed is not updated, you should avoid calling the unlimited search service for that feed.

This service is intended to be used by technically advanced publishers who wish to save the data it their own database, and process it on their own.

The syntax of the unlimited feed last updated service is:

HTTP[S] GET http://api.tradedoubler.com/1.0/productsUnlimited/lastUpdated[.xml|.json|empty];fid={feedId}?token={token}[&jsonp=myCallback]

Query keys

These are the keys you can use in your request:

Name Description Type Required
token Your unique token, identifying you as a publisher. String Yes
fid Primary key of the feed you are requesting. Integer Yes
pretty Set to true for nice line breaks in the output. Boolean No

Example request

Get last updated time for feed ID 123 as JSON:

HTTP[S] GET http://api.tradedoubler.com/1.0/productsUnlimited/lastUpdated.json;fid=123?token={token}

Example response

Response for feed ID 123 as JSON:

...
{
    "feedIds": [
        123
    ],
    "lastUpdatedTime": "2024-04-17T15:57:00.470742"
}
...

The above response shows last updated time for feed id 123. Below are the details for each response elements you can expect

  • feedIds - a list of feed ids requested. Currently only one valid feed id is expected as part of the response as we are supporting only one feed id for each unlimited feed file.
  • lastUpdatedTime - Time when an unlimited feed file was last updated in Tradedoubler system. The lastUpdatedTime support ISO-8601 formats and can be one of below formats:
    • YYYY-MM-dd'T'HH:mm
    • YYYY-MM-dd'T'HH:mm:ss
    • YYYY-MM-dd'T'HH:mm:ss.SSS
    • YYYY-MM-dd'T'HH:mm:ss.SSSSSS
    • YYYY-MM-dd'T'HH:mm:ss.SSSSSSSSS

Categories Service

All products must belong to at least one category - a Tradedoubler or advertiser category - when being created. Until a product is mapped to a Tradedoubler category it will not be available for publishers.

There are three ways for a product to be mapped to a Tradedoubler category:

  1. The advertiser provides the Tradedoubler category when creating the product (in addition to, or instead of, their own category). Tradedoubler will automatically map the products to the stated Tradedoubler category.
  2. The advertiser uses the Create Mapping service to map their categories to Tradedoubler categories. When creating products the advertiser need only include their category name. Tradedoubler will automatically map the products to the corresponding Tradedoubler category.
  3. If mapping is not done by the advertiser, Tradedoubler personnel manually map the advertiser category to a Tradedoubler category. This can take many weeks, during which time the products are not available to publishers, and is strongly discouraged.

Use the services below to check your current category mapping status, retrieve the Tradedoubler category tree, and create mappings between the advertiser and Tradedoubler categories.

Category Tree

The Tradedoubler category tree is available using the following syntax:

HTTP[S] GET http://api.tradedoubler.com/1.0/productCategories[.{json|xml|empty}][;language={language|empty}]?token={token}

These are the keys you can use in your request:

Name Description Required
token Your unique token, identifying you as an advertiser. Yes
language ISO 639-1 code of the language to use in the response. For example en for English or sv for Swedish. No
jsonp If you are requesting JSON, you can define a callback name. The API will return a Javascript document with the result as an array in a function named as the callback. No
The API will return categories in English by default. If you enter a language that the categories have not been translated to, the API also returns English category names.

XML schema

An XSD file for the output format is available here:

Name File
Output format CategoryTree_v1_0.xsd

Category Tree Response

As a response to your request, you can expect the following information:

Name Description
language Language of the category name.
name Name of the category in the language you specified. Defaults to English.
id Unique category identifier which does not change.
productCount Total number of products mapped to this category in feeds associated with the token provided.

If a category has subcategories, these are presented as children in the JSON or XML.

Fetch JSON tree Click here to fetch the category tree in English as JSON:

Data not loaded

Fetch XML tree Click here to fetch the category tree in English as XML:

Data not loaded
Stay current and use the productCategories service to get an up to date tree, instead of using a static tree.

Mapping Status

The Mapping Status service allows you to check the status of your categories. This includes if they are mapped to a Tradedoubler category or not and if so, which one they are mapped to.

The service is accessed using the following syntax:

HTTP[S] GET http://api.tradedoubler.com/1.0/categoryMappings[.{json|xml|empty}];fid={feedId}[;state={unmapped|mapped|empty}][;format={json|xml|empty}][;pretty={true|false|empty}]?token={token}[&jsonp=myCallback]

These are the keys you can use in your request:

Name Description Required
token Your unique token, identifying you as an advertiser. Yes
fid ID of the feed(s) to query. Separate multiple feed IDs with a comma (,). Yes
state Set to 'unmapped' to return unmapped categories or 'mapped' to get already mapped categories. Leave empty to retrieve the status of all categories (mapped and unmapped). Defaults to empty. No
pretty Prints response in a more readable format. No
jsonp If you are requesting JSON, you can define a callback name. The API will return a Javascript document with the result as an array in a function named as the callback. No

Example requests

Get all unmapped categories from feed ID 123 as JSON:

HTTP[S] GET http://api.tradedoubler.com/1.0/categoryMappings;fid=123;state=unmapped?token={token}

Get all categories (mapped and unmapped) from feed ID 123 and 456 as JSON:

HTTP[S] GET http://api.tradedoubler.com/1.0/categoryMappings;fid=123,456?token={token}

Mapping Status Response

As a response to your request, you can expect the following information:

Name Description
totalAvailableObjectCount The total number of category mappings found for the token.
feedId ID of the feed that the category mapping belongs to.
externalCategoryName Advertiser's name for the category.
tdCategoryId Tradedoubler category identifier.

In JSON:

{
	"totalAvailableObjectCount" : 2,
	"categoryMappings" : [
		{
			"feedId" : "12345",
			"externalCategoryName" : "cat1",
			"tdCategoryId" : 1
		},
		{
			"feedId" : "12345",
			"externalCategoryName" : "cat2",
			"tdCategoryId" : 2
		}
	]
}

In XML:

<ns2:categoryMappings version="3.0" xmlns:ns2="urn:com:tradedoubler:pf:model:xml:output" xmlns="urn:com:tradedoubler:pf:model:xml:common">
    <ns2:categoryMapping>
        <feedId>12345</feedId>
        <externalCategoryName>cat1</externalCategoryName>
        <tdCategoryId>1</tdCategoryId>
    </ns2:categoryMapping>
    <ns2:categoryMapping>
        <feedId>12345</feedId>
        <externalCategoryName>cat2</externalCategoryName>
        <tdCategoryId>2</tdCategoryId>
    </ns2:categoryMapping>
</ns2:categoryMappings>

Create Mapping

The Create Mapping service allows you to create new mappings between your categories and Tradedoubler categories.

Once an advertiser category has been mapped to a Tradedoubler category, you do not need to state the Tradedoubler category ID when creating/updating products. Instead, you just include your own category name and Tradedoubler will know which Tradedoubler category to map it to.

The service is accessed using the following syntax:

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

This is the data to post:

Name Description Required
externalCategoryName Advertiser category name. Yes
feedId Advertiser feed identifier. Yes
tdCategoryId Tradedoubler category identifier. Yes

Here are examples of how the post data should be built:

In JSON:

{
  "categoryMappings": [
      {
          "externalCategoryName": "Books",
          "feedId": 19274,
          "tdCategoryId": 2346
      },
      {
          "externalCategoryName": "Childrens' Toys",
          "feedId": 19274,
          "tdCategoryId": 2381
      }
  ]
}

In XML:

<?xml version="1.0" encoding="UTF-8"?>
<td:categoryMappings version="3.0" xmlns:td="urn:com:tradedoubler:pf:model:xml:input" xmlns="urn:com:tradedoubler:pf:model:xml:common">
  <td:categoryMapping>
    <feedId>19274</feedId>
    <externalCategoryName>Books</externalCategoryName>
    <tdCategoryId>2346</tdCategoryId>
  </td:categoryMapping>
  <td:categoryMapping>
    <feedId>19274</feedId>
    <externalCategoryName>Childrens' Toys</externalCategoryName>
    <tdCategoryId>2381</tdCategoryId>
  </td:categoryMapping>
</td:categoryMappings>

Product feed service

The product feed service allows you to get general information about your feeds including name, status, number of products and unmapped categories.

The syntax of the productFeeds service is:

HTTP[S] GET http://api.tradedoubler.com/1.0/productFeeds{/feedId}[.xml|.json|empty]?token={token}[&jsonp=myCallback]

Query keys

These are the query keys available for productFeeds requests:

Name Description Type Required
token Your unique token, identifying you as an advertiser. String Yes
pretty Set to true to get nice line breaks in the response. Boolean No
To lookup a specific feed, add its ID as a path to the URL. For example: /1.0/productFeeds/123?token={token}

Example requests

Get all feeds as JSON:

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

Get feed ID 123 as XML:

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

Filter feeds from program IDs:

HTTP[S] GET http://api.tradedoubler.com/1.0/productFeeds;programId=id1,id2;?token={token}

Response

Here is an example of a response in JSON:

{
  "feeds" : [ {
    "feedId" : 19750,
    "name" : "Carl Example Feed",
    "active" : true,
    "sendToNewPF" : false,
    "visible" : true,
    "currencyISOCode" : "GBP",
    "languageISOCode" : "sv",
    "secret" : false,
    "numberOfUnmappedCategories" : 0,
	"numberOfProducts" : 189905,
	"lastModifiedTime" : "2020-01-01T9:09:03.374+0200",
    "programs" : [ {
      "programId" : 231514,
      "name" : "Carl Example program UK"
    }, {
      "programId" : 228139,
      "name" : "Carl Example program SE"
    } ]
  }, {
    "feedId" : 20782,
    "name" : "Carl test",
    "active" : true,
    "sendToNewPF" : false,
    "visible" : true,
    "currencyISOCode" : "SEK",
    "languageISOCode" : "en",
    "secret" : false,
    "numberOfUnmappedCategories" : 7,
	"numberOfProducts" : 13727,
	"lastModifiedTime" : "2020-01-01T12:09:03.374+0200",
    "programs" : [ {
      "programId" : 50000,
      "name" : "Carl 50k party program"
    } ]
  } ]
}

Error management

When an error occurs in the API, we try to describe the problem in detail. Here are the available error messages.

Module Error code HTTP code HTTP status Description
Open API 1 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
Products API PF_200 400 Bad Request Parameters is missing
Products API PF_210 400 Bad Request No parsable content received
Products API PF_230 400 Bad Request An error not expected and not known
Products API PF_240 400 Bad Request Value not set on a parameter, e.g. a Category of a Product
Products API PF_250 400 Bad Request Our system is experiencing internal problems and cannot serve the request passed at this moment in time
Products API PF_260 400 Bad Request Value expected to be numeric but was not
Products API PF_270 400 Bad Request Value expected to be comma separated
Products API PF_280 400 Bad Request Price could not be parsed from posted data
Products API PF_290 400 Bad Request The currency of the Price is not a valid ISO currency
Products API PF_300 400 Bad Request Token request is not valid
Products API PF_391 400 Bad Request A malformed URL was supplied
Products API PF_392 400 Bad Request Query against a feed not belonging to a program of caller
Products API PF_430 400 Bad Request Parameter has illegal value

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