General
idealo Business API to get detailed click reports (asynchronously) and daily click reports (synchronously).
The base address of the API in production is: https://businessapi.idealo.com
Breaking changes
Changes from version 1 of the detailed click report to version 2.
-
The summary line at the end of the report has been removed.
-
The column order has changed. A new column "ean" has been added before the "cpc" column.
-
Restrictions how often the report can be triggered have been added. See the "General" section for details.
Authentication
Credentials
To access the API you need a client id and a client secret. You can generate some new credentials in idealo business, under 'My idealo' → 'Settings' → 'API clients' → 'idealo business API'.
|
Note
|
The client secret is only shown once at creation time! If you have no longer access or forgot your client secret, please create new credentials and delete the old one. |
OAuth2 steps
The idealo business APIs are secured by OAuth2. At a high level, you follow four steps:
-
Obtain OAuth 2.0 Credentials from idealo business
-
Obtain an Get Access Token from https://businessapi.idealo.com/api/v1/oauth/token
-
Do an API request
-
The access token expires after 3600 seconds and you need get a new Get Access Token like before.
Get Access Token
POST /api/v1/oauth/token
Returns the access token for the idealo Business API. You need to provide the access token for every secured endpoint in the API.
Request headers
| Header | Type | Optional | Description |
|---|---|---|---|
Authorization |
Object |
false |
The client credentials client id and secret. |
Response fields
| Path | Type | Optional | Description |
|---|---|---|---|
access_token |
String |
false |
The access-token that is used for authentication. You need to provide it in the authorization header when you fetch data from the api. |
token_type |
String |
false |
The tokens type. In this case it’s bearer. |
expires_in |
Integer |
true |
The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. You need to fetch a new token when it is expired. |
scope |
String |
false |
The scopes for this token. |
shop_id |
Integer |
true |
The shopId the access-token is valid for. |
Example request
$ curl 'https://businessapi.idealo.com/api/v1/oauth/token' -i -u '51f060d4-7893-4dd5-975f-8566ff5ece60:Y0ur-Cl13nt-S3cr3t' -X POSTExample response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 868
{
"access_token" : "eyJraWQiOiJ0ZXN0LWtleS1pZCIsImFsZyI6IlJTMjU2In0.eyJqdGkiOiIxYTdhZDhmYS05NjFkLTQ2YmYtYTU3NS01OTcyNTNmYzg4MGQiLCJpc3MiOiJhdXRob3JpemF0aW9uc2VydmVyIiwiaWF0IjoxNjYwNTczNjkxLCJleHAiOjE2NjA1NzQ2OTEsImF1ZCI6ImJ1c2luZXNzYmFja2VuZCIsImF1dGhvcml0aWVzIjpbIlJPTEVfRVhURVJOQUxfQ0xJRU5UIl0sInNjb3BlIjpbIkJVU0lORVNTQkFDS0VORDpDUkVBVEVfT0ZGRVJSRVBPUlQiLCJCVVNJTkVTU0JBQ0tFTkQ6UkVBRF9QRVJGT1JNQU5DRVJFUE9SVCIsIkJVU0lORVNTQkFDS0VORDpDUkVBVEVfUFJJQ0VSRVBPUlQiLCJCVVNJTkVTU0JBQ0tFTkQ6Q1JFQVRFX0NMSUNLUkVQT1JUIiwiQlVTSU5FU1NCQUNLRU5EOlJFQURfT0ZGRVJSRVBPUlQiLCJCVVNJTkVTU0JBQ0tFTkQ6UkVBRF9QUklDRVJFUE9SVCIsIkJVU0lORVNTQkFDS0VORDpSRUFEX0NMSUNLUkVQT1JUIiwiQlVTSU5FU1NCQUNLRU5EOkNSRUFURV9QRVJGT1JNQU5DRVJFUE9SVCJdLCJjbGllbnRfaWQiOiI0Y2U5ZjJiNC1mNDg5LTQxYWEtYWFjOS1jYjE3MjNjNTliNjMiLCJzaG9wX2lkIjoxfQ.VTduD6hCUtWNYf8KubFyvGEtFYr2CXse1mTRlRvNUEXwGgqgpL0IHxY-irdxENwhv4HoeW_lXFH8XQrk_55wYJn7im2cUkXCllo9lYBa9mKRPCq8dq2yv8mD3bShBnmrKiSDt3_-NgE2Xt2Xo0YqiY9YAkztQxjjeeDnjcSWULeBDRgxx2w7IYe6yLk5T8mevGWiTUkN48vLPNkH2zJSW1n3EQm41DqTEjTX2Dqn-ENcdVWyUliY8fMqAB6CGveAfKqHW4PL-iMU4f7q_pJDkxGJFibN9Kl9wBTLGGjzxfuU5tsrwUwaHd2spEQt0C0DZG9bOprFiZXTqVOB8lg-zg",
"token_type" : "bearer",
"expires_in" : 3600,
"scope" : "BUSINESSBACKEND:CREATE_PRICEREPORT,BUSINESSBACKEND:READ_PRICEREPORT",
"shop_id" : 1
}Click report operations V2
|
Note
|
Detailed click report request are limited to 5 per 24 hours and the delay between two reports has to be at least 15 minutes. If any of these limits is reached, report request will be blocked with HTTP code 429 (Too many request). |
|
Note
|
If you are migrating from V1, please consider the Breaking changes |
Start Report
POST /api/v2/shops/{shopId}/click-reports
Path parameters
| Parameter | Type | Optional | Description |
|---|---|---|---|
shopId |
Integer |
false |
Request fields
| Path | Type | Optional | Description |
|---|---|---|---|
from |
String |
true |
|
to |
String |
true |
Response fields
| Path | Type | Optional | Description |
|---|---|---|---|
status |
String |
true |
Must be one of [PROCESSING, FAILED, SUCCESSFUL]. |
startTime |
String |
true |
|
endTime |
String |
true |
|
id |
String |
true |
|
shopId |
Integer |
true |
|
from |
String |
true |
|
to |
String |
true |
Example request
$ curl 'https://businessapi.idealo.com/api/v2/shops/12345/click-reports' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJraWQiOiJ0ZXN0LWtleS1...' \
-d '{"from":"2025-04-29","to":"2025-04-30"}'Example response
HTTP/1.1 201 Created
Content-Type: application/json
{
"status" : "PROCESSING",
"id" : "d689c50d-82ac-4aff-8a3a-4ca6eee2d42b",
"shopId" : 12345,
"from" : "2025-04-29",
"to" : "2025-04-30"
}Get Report
GET /api/v2/shops/{shopId}/click-reports/{reportId}
Path parameters
| Parameter | Type | Optional | Description |
|---|---|---|---|
shopId |
Integer |
false |
|
reportId |
Object |
false |
Response fields
| Path | Type | Optional | Description |
|---|---|---|---|
status |
String |
true |
Must be one of [PROCESSING, FAILED, SUCCESSFUL]. |
startTime |
String |
true |
|
endTime |
String |
true |
|
id |
String |
true |
|
shopId |
Integer |
true |
|
from |
String |
true |
|
to |
String |
true |
Example request
$ curl 'https://businessapi.idealo.com/api/v2/shops/12345/click-reports/d689c50d-82ac-4aff-8a3a-4ca6eee2d42b' -i -X GET \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJraWQiOiJ0ZXN0LWtleS1...'Example response
HTTP/1.1 200 OK
Content-Type: application/json
{
"status" : "SUCCESSFUL",
"startTime" : "2024-12-22T15:07:49.795Z",
"endTime" : "2024-12-22T15:08:04.394Z",
"id" : "d689c50d-82ac-4aff-8a3a-4ca6eee2d42b",
"shopId" : 12345,
"from" : "2024-10-01",
"to" : "2024-10-02"
}Download Report
GET /api/v2/shops/{shopId}/click-reports/{reportId}/download
Path parameters
| Parameter | Type | Optional | Description |
|---|---|---|---|
shopId |
Integer |
false |
|
reportId |
Object |
false |
Example request
$ curl 'https://businessapi.idealo.com/api/v2/shops/12345/click-reports/d689c50d-82ac-4aff-8a3a-4ca6eee2d42b/download' -i -X GET \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJraWQiOiJ0ZXN0LWtleS1...'Example response
HTTP/1.1 200 OK
Content-Disposition: attachment; filename=report_click_cost_2024-10-01_2024-10-02.csv.zip
Content-Type: application/octet-stream
<binary>Daily click report operations
Download Daily Click Report
GET /api/v1/shops/{shopId}/daily-click-reports/download
Path parameters
| Parameter | Type | Optional | Description |
|---|---|---|---|
shopId |
Integer |
false |
Query parameters
| Parameter | Type | Optional | Description |
|---|---|---|---|
from |
String |
true |
Start date of the time frame for which the data should be processed. e.g. from=2019-05-01 |
to |
String |
true |
End date of the time frame for which the data should be processed. e.g. to=2019-05-01 |
Response fields
| Path | Type | Optional | Description |
|---|---|---|---|
uri |
String |
true |
|
description |
String |
true |
|
open |
Boolean |
true |
|
file |
String |
true |
|
readable |
Boolean |
true |
|
url |
String |
true |
|
filename |
String |
true |
|
contentAsByteArray |
Array[Integer] |
true |
|
inputStream |
Object |
true |
Example request
$ curl 'https://businessapi.idealo.com/api/v1/shops/12345/daily-click-reports/download?from=2025-05-23&to=2025-05-30' -i -X GET \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJraWQiOiJ0ZXN0LWtleS1...'Example response
HTTP/1.1 200 OK
Content-Disposition: attachment; filename=report_daily_clicks_2025-05-23_2025-05-30.csv
Content-Type: application/octet-stream
<binary>Click report operations V1 (deprecated)
|
Note
|
This API is deprecated, please use version 2 of this api. See Click report operations V2. |
Start Report
POST /api/v1/shops/{shopId}/click-reports
Path parameters
| Parameter | Type | Optional | Description |
|---|---|---|---|
shopId |
Integer |
false |
Request fields
| Path | Type | Optional | Description |
|---|---|---|---|
from |
String |
true |
|
to |
String |
true |
Response fields
| Path | Type | Optional | Description |
|---|---|---|---|
status |
String |
true |
Must be one of [PROCESSING, FAILED, SUCCESSFUL]. |
startTime |
String |
true |
|
endTime |
String |
true |
|
id |
String |
true |
|
shopId |
Integer |
true |
|
from |
String |
true |
|
to |
String |
true |
Example request
$ curl 'https://businessapi.idealo.com/api/v1/shops/12345/click-reports' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJraWQiOiJ0ZXN0LWtleS1...' \
-d '{"from":"2025-05-23","to":"2025-05-30"}'Example response
HTTP/1.1 201 Created
Content-Type: application/json
{
"status" : "PROCESSING",
"id" : "d689c50d-82ac-4aff-8a3a-4ca6eee2d42b",
"shopId" : 12345,
"from" : "2022-10-01",
"to" : "2022-10-02"
}Get Report
GET /api/v1/shops/{shopId}/click-reports/{reportId}
Path parameters
| Parameter | Type | Optional | Description |
|---|---|---|---|
shopId |
Integer |
false |
|
reportId |
Object |
false |
Response fields
| Path | Type | Optional | Description |
|---|---|---|---|
status |
String |
true |
Must be one of [PROCESSING, FAILED, SUCCESSFUL]. |
startTime |
String |
true |
|
endTime |
String |
true |
|
id |
String |
true |
|
shopId |
Integer |
true |
|
from |
String |
true |
|
to |
String |
true |
Example request
$ curl 'https://businessapi.idealo.com/api/v1/shops/12345/click-reports/d689c50d-82ac-4aff-8a3a-4ca6eee2d42b' -i -X GET \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJraWQiOiJ0ZXN0LWtleS1...'Example response
HTTP/1.1 200 OK
Content-Type: application/json
{
"status" : "SUCCESSFUL",
"startTime" : "2022-12-22T15:07:49.795Z",
"endTime" : "2022-12-22T15:08:04.394Z",
"id" : "d689c50d-82ac-4aff-8a3a-4ca6eee2d42b",
"shopId" : 12345,
"from" : "2022-10-01",
"to" : "2022-10-02"
}Download Report
GET /api/v1/shops/{shopId}/click-reports/{reportId}/download
Path parameters
| Parameter | Type | Optional | Description |
|---|---|---|---|
shopId |
Integer |
false |
|
reportId |
Object |
false |
Example request
$ curl 'https://businessapi.idealo.com/api/v1/shops/12345/click-reports/d689c50d-82ac-4aff-8a3a-4ca6eee2d42b/download' -i -X GET \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJraWQiOiJ0ZXN0LWtleS1...'Example response
HTTP/1.1 200 OK
Content-Disposition: attachment; filename=report_detailed_clicks_2022-10-01_2022-10-02.csv.zip
Content-Type: application/octet-stream
<binary>