Get list of merchants

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.

If you receive an empty list of merchants, but the next value in the response is not null — request the following page of the merchants list, using the next query parameter with the next value from the received response.

If no query parameters are specified, the list with up to 100 first merchants is returned.

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

Request

URL: https://api.takeads.com/v1/product/monetize-api/v2/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 Authorization 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 updatedAtFrom parameter. It allows you to limit the list of merchants only to those who were updated after the specified date.

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

next
(optional)

integer

Pointer (integer) to the next page of the merchant list. If specified, a list of merchants from the indicated page is retrieved.

limit
(optional)

integer

Maximum number of merchants that may be returned for a single request. The maximum value is 500. The default value is 100.

updatedAtFrom
(optional)

string

Lower border of the updatedAt field to filter (included). It specifies the starting point of the period during which information about merchants was last updated. Date and time in the ISO 8601 format.

Example: Example: 2021-08-03T19:53:15.816Z

isActive
(optional)

boolean

Status of the merchant.

A merchant is active if it has at least one active program.

Request examples


  • curl --request GET \
    --url 'https://api.takeads.com/v1/product/monetize-api/v2/merchant?next=1&updatedAtFrom=2024-01-01&limit=100&isActive=true' \ --header 'Authorization: Bearer <Public Key>'\ --header 'Content-Type: application/json'
  • fetch("https://api.takeads.com/v1/product/monetize-api/v2/merchant?next=1&updatedAtFrom=2024-01-01&limit=100&isActive=true", {
    "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/product/monetize-api/v2/merchant?next=1&updatedAtFrom=2024-01-01&limit=100&isActive=true",
    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/product/monetize-api/v2/merchant?next=1&updatedAtFrom=2024-01-01&limit=100&isActive=true", 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 metadata.

Property Type Description
next integer Pointer (integer) to the next page of the merchant list. If specified, a list of merchants from the indicated page is retrieved.

The following table describes the response properties from the data array.

Property Type Description
merchantId number / null Merchant unique identifier.
name string Merchant name
imageUri string / null URI of the merchant’s logo.
defaultDomain string Default merchant domain.
description string Merchant description.
categoryId integer List of merchant category IDs.
domains array List of merchant domains.
currencyCode string Currency code in ISO 4217:2008 alpha-3 format.
isActive boolean

Status of the merchant.

A merchant is active if it has at least one active program.

countryCodes array List of country codes in ISO 3166-1 alpha-2 format where the program operates.
averageBasketValue number Average purchases number for the merchant.
averageCommission number Average percent of the merchant's commission.
averageConfirmationTime integer Average commission confirmation time in days.
averageCancellationRate number Average rate of cancelled commission.
minimumCommission number Minimum commission value.
maximumCommission number Maximum commission value.
commissionRates array List of rewards the publisher can receive from the merchant for each approved action. These rates reflect the potential earnings for different types of actions performed by the publisher's audience. The exact reward received depends on the actions validated and approved by the merchant.
fixedCommission number Set amount paid per transaction or lead.
percentageCommission number Percentage of the total sale amount paid per transaction.
trackingLink string Merchant tracking link.
createdAt string Timestamp ($ISO 8601) that specifies the date when of the last update of the merchant.

Example: 2021-08-03T19:53:15.816Z
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": {
"next": 1234
},
"data": [
{
"merchantId": 12345,
"name": "ACME",
"imageUri": "https://sitesample.com/image.svg",
"defaultDomain": "sitesample.com",
"description": "Some description",
"categoryId": 12,
"domains": [
"sitesample.com"
],
"currencyCode": "EUR",
"isActive": true,
"countryCodes": [
"DE"
],
"averageBasketValue": 120.45,
"averageCommission": 4.45,
"averageConfirmationTime": 39,
"averageCancellationRate": 0.45,
"minimumCommission": 0,
"maximumCommission": 0,
"commissionRates": [
{
"fixedCommission": 1.4,
"percentageCommission": 5.4
}
],
"trackingLink": "https://tatrck.com/h/q1w2e3r4t5y6",
"createdAt": "2023-01-30T08:07:12.166Z",
"updatedAt": "2023-01-30T08:07:12.166Z"
}
]
}

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