Get list of merchants

Updated June 21, 2023 13:39

Use this endpoint to receive the list of merchants available in Takeads catalog.

A merchant is a company that sells its products or services through one or more advertisers. For example, as a merchant, Nike distributes products through the following advertisers: nike.com, nike.eu, nike.de, etc.

When querying a list of merchants, details about each merchant from the list are also provided in the response.

You can test this API endpoint and inspect the possible responses using Swagger UI.

Request

URL: https://api.takeads.com/v1/api/merchant

Method: GET

Request headers

Header

Value

Description

Authorization

Bearer <PublicKey>

String of alphanumeric characters with Bearer as prefix, used to authenticate and authorize your API requests.

To learn how to get your Public key, refer to the Receiving API keys article.

Query Parameters

You can use query parameters to get information on specific merchants, or paginate the response.

This endpoint has no required parameters. If no query parameters are specified, the list of the first 500 merchants is returned.

You can get a list of merchants, information about which was last updated during the specified period. To specify the period, use one of the following: days parameter, or date parameter, or a pair of dateFrom and dateTo parameters.

If days parameter is specified — date, dateFrom and dateTo parameters are ignored.
If days parameter is not specified and date parameter is specified — dateFrom and dateTo parameters are ignored.

The specified period cannot exceed 120 days.

Use offset and limit parameters to paginate the response.

The following table describes query parameters that you can use in the request.

Property	Type	Description
dateFrom (optional)	string	Starting point of the sampling period. This parameter can't be used without the ending point of the filtering period — `dateTo`. Example: 2021-08-03
dateTo (optional)	string	Ending point of the sampling period. This parameter can't be used without the starting point of the filtering period — `dateFrom`. Example: 2021-08-04
date (optional)	string	Exact sampling date. Example: 2021-08-03
days (optional)	integer	Number of days in the sampling period. Defaults to 7. Example: 3 The starting date of the sampling period can be defined by the current date minus the number of `days`.
offset (optional)	integer	If specified, the list of merchants starting with the `offset` value is retrieved. The first N merchants are excluded from the response (N = offset value). The default value is 0.
limit (optional)	integer	The maximum number of merchants that may be returned for a single request. The default value is 500. The maximum value is 500.

Request examples


curl --request GET \

  --url 'https://api.takeads.com/v1/api/merchant?dateFrom=2021-08-03&dateTo=2021-08-04&limit=100&offset=500' \
  --header 'Authorization: Bearer <Public Key>'\
  --header 'Content-Type: application/json'

fetch("https://api.takeads.com/v1/api/merchant?dateFrom=2021-08-03&dateTo=2021-08-04&limit=100&offset=500", {

  "method": "GET",

  "headers": {

    "Authorization": "Bearer <Public Key>",

    "Content-Type": "application/json"

  }

})

.then(response => {

  console.log(response);

})

.catch(err => {

  console.error(err);

});

<?php

 
$curl = curl_init();

 
curl_setopt_array($curl, [

  CURLOPT_PORT => "6110",

  CURLOPT_URL => "https://api.takeads.com/v1/api/merchant?dateFrom=2021-08-03&dateTo=2021-08-04&limit=100&offset=500",

  CURLOPT_RETURNTRANSFER => true,

  CURLOPT_ENCODING => "",

  CURLOPT_MAXREDIRS => 10,

  CURLOPT_TIMEOUT => 30,

  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,

  CURLOPT_CUSTOMREQUEST => "GET",

  CURLOPT_POSTFIELDS => "",

  CURLOPT_HTTPHEADER => [

    "Authorization: Bearer <Public Key>",

    "Content-Type: application/json"

  ],

]);

 
$response = curl_exec($curl);

$err = curl_error($curl);

 
curl_close($curl);

 
if ($err) {

  echo "cURL Error #:" . $err;

} else {

  echo $response;

}

import http.client
 
conn = http.client.HTTPSConnection("https://api.takeads.com")
 
payload = ""
 
headers = {

    'Authorization': "Bearer <Public Key>",

    'Content-Type': "application/json"

    }
 
conn.request("GET", "/v1/api/merchant?dateFrom=2021-08-03&dateTo=2021-08-04&limit=100&offset=500", payload, headers)
 
res = conn.getresponse()

data = res.read()
 
print(data.decode("utf-8"))

Response

If the request was successfully processed by the server, the HTTP response with 200 status code and the list of available merchants is returned.

The response payload is a JSON object that contains a meta object with metadata and a data array with the merchants' details. Each item of the array is an object with the details about the merchants retrieved according to request.

The following table describes the response properties.

Property	Type	Description
offset	integer	If specified, the list of merchants starting with the `offset` value is retrieved. The first N merchants are excluded from the response (N = offset value). The default value is 0.
limit	integer	The maximum number of merchants that may be returned for a single request. The default value is 500. The Maximum value is 500.
total	integer	Total number of merchants in the Takeads catalog that are corresponding to the specified parameters.
id	number / null	Merchant ID.
name	string	Name of a merchant.
updatedAt	string	Timestamp ($ISO 8601) when information about the merchant was last updated in the Takeads catalog. Example: 2021-08-03T19:53:15.816Z

Example value

{

  "meta": {

    "limit": 500,

    "offset": 0,

    "total": 10

  },

  "data": [

    {

      "id": 110621,

      "name": "Otto",

      "updatedAt": "2022-06-03T05:45:24.000Z"

    },

    …

  ]

}

To view possible error responses, refer to the Error responses article.

Was this article helpful?

0 out of 0 found this helpful