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.

  1. The summary line at the end of the report has been removed.

  2. The column order has changed. A new column "ean" has been added before the "cpc" column.

  3. Restrictions how often the report can be triggered have been added. See the NOTES of the Click report V2 operations section for details.

  4. The report includes data starting from up to 15 months ago. It can contain data up to the previous day only — today’s data is not included. Data for the previous day is typically available from around 5:00 AM UTC.

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:

  1. Obtain OAuth 2.0 Credentials from idealo business

  2. Obtain an Get Access Token from https://businessapi.idealo.com/api/v1/oauth/token

  3. Do an API request

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

Example 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 V2 operations

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

Triggers the creation of a new report for the specified shop id and parameters. If a report is already in progress for the specified shop id an error (409) will be thrown.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Your idealo shop ID.

Request fields

Path Type Optional Description

from

String

true

Start date of the time frame for which the data should be processed.

to

String

true

End date of the time frame for which the data should be processed.

Response fields

Path Type Optional Description

status

String

true

The current status of the report.Indicates the processing state of the report.

Must be one of [PROCESSING, FAILED, SUCCESSFUL].

startTime

String

true

The timestamp when report generation started.

endTime

String

true

The timestamp when report generation finished. May be null if the report is still in progress or failed before completion.

id

String

true

Unique identifier of the report.

shopId

Integer

true

Identifier of the shop for which the report is generated.

from

String

true

Start date of the time frame for which the data should be processed.

to

String

true

End date of the time frame for which the data should be processed.

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-07-02","to":"2025-07-03"}'

Example response

HTTP/1.1 201 Created
Content-Type: application/json

    {
    "status" : "PROCESSING",
    "startTime" : "2025-09-03T11:49:33.219836Z",
    "id" : "d689c50d-82ac-4aff-8a3a-4ca6eee2d42b",
    "shopId" : 12345,
    "from" : "2025-07-02",
    "to" : "2025-07-03"
}

Get Report

GET /api/v2/shops/{shopId}/click-reports/{reportId}

Returns the report for the specified report id.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Your idealo shop ID.

reportId

Object

false

Unique identifier of the report.

Response fields

Path Type Optional Description

status

String

true

The current status of the report.Indicates the processing state of the report.

Must be one of [PROCESSING, FAILED, SUCCESSFUL].

startTime

String

true

The timestamp when report generation started.

endTime

String

true

The timestamp when report generation finished. May be null if the report is still in progress or failed before completion.

id

String

true

Unique identifier of the report.

shopId

Integer

true

Identifier of the shop for which the report is generated.

from

String

true

Start date of the time frame for which the data should be processed.

to

String

true

End date of the time frame for which the data should be processed.

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

Downloads the report for the specified report id.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Your idealo shop ID.

reportId

Object

false

Unique identifier of the report.

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>

Description of the columns (CSV)

The following table lists all columns of the detailed click report (CSV), including data types, examples, and a brief description.

Column Name Type Example Description

Date

Datetime in ISO 8601 format

2025-06-17T19:07:16

Timestamp of the click event in Berlin local time (Europe/Berlin).

Product

String

BlueWalker PowerWalker VI 2000 RLP

Full product name, including the brand, as listed on idealo at the time of the click.

idealo Product ID

String

201899510

Stable identifier assigned by idealo to the product.

Category

String

Elektroartikel > Computer > PC-Komponenten > RAM

Product category path on idealo at the time of the click (levels separated by " > ").

Customer-IP

String

20a5f33…​7f0714q73

Customer IP address hashed for privacy. Raw IPs are not exposed.

Click Type

String

offer

Type of interaction that generated the click, please see List of possible click types.

Site/Partner

String

idealo.de, idealo.at, idealo.fr, auspreiser.at, pepper.com

The name of the site or partner where the click occurred.

Link

URL

https://www.my-shop.de/angebote/12345

Destination URL recorded for the click.

Sku

String

ABC-123

Shop’s SKU of the offer (SKU = Stock keeping unit).

EANs

String

8592978481827

One or more EAN or GTIN values defined on the related idealo product of the offer (EAN = European Article Number, now replaced by GTIN = Global Trade Item Number).

Cpc

Decimal

0.60

Cost per click charged for the offer.

List of possible click types

Click type Description

offer

Clicks on offers in product catalog

offer LPI

Clicks on low price inventory offers in product catalog

offer open catalog

Clicks on offers in open catalog

offer open catalog LPI

Clicks on low price inventory offers in open catalog

local offer

Clicks on local offers

local offer LPI

Clicks on local low price inventory offers

Daily click report operations

Download Daily Click Report

GET /api/v1/shops/{shopId}/daily-click-reports/download

Creates and downloads a daily click report for the specified shop id and parameters.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Your idealo shop ID.

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=2025-05-01

to

String

true

End date of the time frame for which the data should be processed.

e.g. to=2025-08-01

Example request

$ curl 'https://businessapi.idealo.com/api/v1/shops/12345/daily-click-reports/download?from=2025-07-27&to=2025-08-03' -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-07-27_2025-08-03.csv
Content-Type: application/octet-stream

<binary>

Click report V1 operations (deprecated)

Note
 This API is deprecated, please use version 2 of this api. See Click report V2 operations.

Start Report

POST /api/v1/shops/{shopId}/click-reports

Triggers the creation of a new report for the specified shop id and parameters. If a report is already in progress for the specified shop id an error (409) will be thrown.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Your idealo shop ID.

Request fields

Path Type Optional Description

from

String

true

Start date of the time frame for which the data should be processed.

to

String

true

End date of the time frame for which the data should be processed.

Response fields

Path Type Optional Description

status

String

true

The current status of the report.Indicates the processing state of the report.

Must be one of [PROCESSING, FAILED, SUCCESSFUL].

startTime

String

true

The timestamp when report generation started.

endTime

String

true

The timestamp when report generation finished. May be null if the report is still in progress or failed before completion.

id

String

true

Unique identifier of the report.

shopId

Integer

true

Identifier of the shop for which the report is generated.

from

String

true

Start date of the time frame for which the data should be processed.

to

String

true

End date of the time frame for which the data should be processed.

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-07-27","to":"2025-08-03"}'

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}

Returns the report for the specified report id.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Your idealo shop ID.

reportId

Object

false

Unique identifier of the report.

Response fields

Path Type Optional Description

status

String

true

The current status of the report.Indicates the processing state of the report.

Must be one of [PROCESSING, FAILED, SUCCESSFUL].

startTime

String

true

The timestamp when report generation started.

endTime

String

true

The timestamp when report generation finished. May be null if the report is still in progress or failed before completion.

id

String

true

Unique identifier of the report.

shopId

Integer

true

Identifier of the shop for which the report is generated.

from

String

true

Start date of the time frame for which the data should be processed.

to

String

true

End date of the time frame for which the data should be processed.

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

Downloads the report for the specified report id.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Your idealo shop ID.

reportId

Object

false

Unique identifier of the report.

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>