General
The idealo Partner Web-Service 2.0 (PWS 2.0) is a stateless web interface, where you are able to maintain your idealo inventory. It attempts to conform to the design principles of Representational State Transfer (REST).
The idealo PWS 2.0 provides several endpoints where you can read (GET), add/update (PUT/PATCH) and delete (DELETE/DELETE All) your offer data. Those are using the JSON data format for requests and responses.
For testing reasons be aware that there is no dedicated testing environment. If you test with your idealo shopID it might affect your current live inventory. Instead, get a test shop instance provided by our Technical Account Management. Please contact tam@idealo.de for it.
Getting Started
Before you can start making requests please ensure to have a valid Access-Token. For details have a look at the Authentication
section. Once you have a valid access token, perform a PUT
- Request to add an offer.
URLs are relative to https://import.idealo.com unless otherwise noted!
URL Format
URLs must be normalised and must not contain non-printable ASCII characters or a
-
semicolon,
-
URL encoded slash,
-
backslash,
-
null character,
-
URL encoded percent.
Authentication
PWS is secured by OAuth2. At a high level, you follow four steps:
-
Obtain OAuth 2.0 Credentials from idealo Business
-
Obtain an Access Token from the Authorization Server
-
Do a PWS request
-
Refresh the Access Token, if necessary
Credentials
To get clientId and clientSecret you need to use idealo business: https://business.idealo.com/direct/mi/settings/api-client
Access Token
To generate an access token, do a POST request against our authorization endpoint and use your clientId and clientSecret for Basic Auth (with extra line breaks for display purposes only):
POST /mer/businessaccount/api/v1/oauth/token HTTP/1.1
Host: api.idealo.com
Authorization: Basic <place your Base64 encoded clientId:clientSecret here>
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
You will receive an access token in the form of a JWT. The JWT can be deciphered manually e.g. using https://jwt.io/:
{
"access_token" : "eyJraWQiOiJrMSIsImFsZyI[...]",
"token_type" : "bearer",
"expires_in" : 3600,
"scope" : "PARTNERWEBSERVICE:READ_OFFER, PARTNERWEBSERVICE:DELETE_OFFER, PARTNERWEBSERVICE:UPDATE_OFFERTIMESTAMP",
"shop_id" : 123456
}
Refresh the Access Token
The access token expires after some time. Per default it is 3600 seconds. So it’s necessary to refresh it. To do so, just get a new one like defined under Access Token.
Limits
Rate Limit
The number of requests that you can send to the PWS is limited per minute. In case the rate limit is reached you will receive a 429 (Too Many Requests) response as described in Rate Limit Error Example.
Size Limit
The size of the message you can send to the PWS is limited, by size, to 395 KB. If the size of the message is too big, you will receive a 413 (Content to Large) response with a message defining the maximum allowed request size.
Error Handling
Error responses are in JSON format with human-readable explanations. It is possible to have multiple error messages in the body of a single response.
JSON payload in the error response
The JSON error response is a simple JSON object that contains error descriptions, depending on if it’s a general validation error or something specific to a field in the request. In some cases, both can be present in the response.
Response fields
Path | Type | Description |
---|---|---|
|
|
A list of strings, which are human readable general validation errors that does not apply to a particular field |
|
|
A list of objects, which describe field specific validation errors |
|
|
Name of the field that was erroneous |
|
|
A human readable error message |
General error example
In this example, the error is that the SKU of the offer provided in the request path does not match the body. This produces a general error.
HTTP response
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 159
{
"fieldErrors" : [ ],
"generalErrors" : [ "Sku in url path (some-sku-123) differs from sku in request body (not-the-same-sku-as-in-the-request-path)!" ]
}
Field error example
Here, the issue is with incorrect decimal format in the price field. This produces a field specific error.
HTTP response
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 156
{
"fieldErrors" : [ {
"field" : "price",
"message" : "Price has has to be provided in format ^\\d{1,9}\\.\\d{2}$"
} ],
"generalErrors" : [ ]
}
Rate Limit Error Example
If the rate limit is exceeded, a 429 response will be returned. The header X-RateLimit-Limit
specifies the currently applied limits. For example 30000;w=60
describes a rate limit of 30,000 requests per 60 seconds.
HTTP response
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Content-Length: 100
X-RateLimit-Limit: 30000;w=60
{
"generalErrors": ["Too many requests per minute. The maximum allowed requests are 30000 per minute."]
}
Resource types
Offer Resource
Allows storage and retrieval of Offers for a given Shop
For generating a client for the API, a JSON Schema can be downloaded. |
GET
Read an Offer.
Example
To GET
an Offer, make the following request:
HTTP request
GET /shop/123/offer/abc3434 HTTP/1.1
Authorization: Bearer <<< OAUTH2_ACCESS_TOKEN_HERE >>>
Accept: application/json
Host: localhost:8080
Path parameters
Parameter | Description |
---|---|
|
Unique shop identifier |
|
Unique offer identifier |
The response will be as follows:
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2019
{
"sku" : "ABC13222",
"title" : "title",
"price" : "12.80",
"formerPrice" : "14.80",
"url" : "https://example.com/my-offer",
"basePrice" : "1,99 € / 100g",
"packagingUnit" : 5,
"voucherCode" : "AUTO10 (10% Rabatt auf alle Produkte der Kategorie Autoreifen bis 31.12.!)",
"branchId" : "branch123",
"brand" : "Sony",
"oens" : [ "VW,123 615 301", "BMW,876 647 9879" ],
"categoryPath" : [ "Clothes, Shoes & Accessories > Men's Clothing > Shorts", "Men's Outdoor > Shorts" ],
"description" : "Digitalkamera EOS D5300 mit 24 MP und optischem Bildstabilisator inklusive Teleobjektiv",
"imageUrls" : [ "https://example.com/philips-hue-weiss-und-farbig-10w-e27.jpg", "https://example.com/produktbild_max/philips-hue-schwarz-10w-e27.jpg" ],
"eans" : [ "123456789012", "4006381333931" ],
"hans" : [ "DMC-TZ10EB-K", "DMC-AB567C-J" ],
"pzns" : [ "03919011", "06893269" ],
"kbas" : [ "46988 205/55R16" ],
"merchantName" : "Example merchant",
"merchantId" : "123456",
"paymentCosts" : {
"CREDIT_CARD" : "2.99",
"INVOICE" : "0.00",
"CASH_IN_ADVANCE" : "0.00",
"PAYPAL" : "1.23"
},
"deliveryCosts" : {
"DHL" : "3.99",
"DPD" : "3.80"
},
"deliveryComment" : "Abholung vor Ort möglich, Lieferung inklusive Altgerätentsorgung",
"delivery" : "1-3 Werktage",
"maxOrderProcessingTime" : 1,
"freeReturnDays" : 20,
"fulfillmentType" : "FREIGHT_FORWARDER",
"twoManHandlingFee" : "20.00",
"disposalFee" : "40.00",
"eec" : "A++",
"energyLabels" : [ {
"efficiencyClass" : "A",
"spectrum" : "A-G",
"labelUrl" : "http://www.example.com/label.jpg",
"dataSheetUrl" : "http://www.example.com/datasheet.pdf",
"version" : 1
} ],
"deposit" : "0.25",
"size" : "small",
"colour" : "black",
"gender" : "neutral",
"material" : "metal",
"replica" : true,
"used" : true,
"download" : true,
"dynamicProductAttributes" : {
"22337" : [ "6" ],
"19326" : [ "39" ]
},
"condition" : "EXCELLENT",
"conditionType" : "USED"
}
PUT
Writes an offer.
Example
A PUT
request requires the following path parameters and request body.
HTTP request
PUT /shop/123/offer/abc3434 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <<< OAUTH2_ACCESS_TOKEN_HERE >>>
Content-Length: 2066
Host: localhost:8080
{
"sku" : "abc3434",
"title" : "My Offer",
"price" : "12.80",
"formerPrice" : "14.80",
"url" : "http://example.com",
"paymentCosts" : {
"PAYPAL" : "2.63"
},
"deliveryCosts" : {
"DHL" : "0.69"
},
"basePrice" : "1,99 € / 100g",
"packagingUnit" : 5,
"voucherCode" : "AUTO10 (10% Rabatt auf alle Produkte der Kategorie Autoreifen bis 31.12.!)",
"branchId" : "branch123",
"brand" : "Sony",
"oens" : [ "VW,123 615 301", "BMW,876 647 9879" ],
"categoryPath" : [ "Clothes, Shoes & Accessories > Men's Clothing > Shorts", "Men's Outdoor > Shorts" ],
"description" : "Digitalkamera EOS D5300 mit 24 MP und optischem Bildstabilisator inklusive Teleobjektiv",
"imageUrls" : [ "https://example.com/philips-hue-weiss-und-farbig-10w-e27.jpg", "https://example.com/produktbild_max/philips-hue-schwarz-10w-e27.jpg" ],
"eans" : [ "123456789012", "4006381333931" ],
"hans" : [ "DMC-TZ10EB-K", "DMC-AB567C-J" ],
"pzns" : [ "03919011", "06893269" ],
"kbas" : [ "46988 205/55R16" ],
"merchantName" : "superSeller",
"merchantId" : "abcde",
"deliveryComment" : "Abholung vor Ort möglich, Lieferung inklusive Altgerätentsorgung",
"delivery" : "1-3 Werktage",
"maxOrderProcessingTime" : 1,
"freeReturnDays" : 20,
"fulfillmentType" : "FREIGHT_FORWARDER",
"twoManHandlingFee" : "20.00",
"disposalFee" : "40.00",
"eec" : "A++",
"energyLabels" : [ {
"efficiencyClass" : "A",
"spectrum" : "A-G",
"labelUrl" : "http://www.example.com/label.jpg",
"dataSheetUrl" : "http://www.example.com/datasheet.pdf",
"fuelEfficiencyClass" : "A",
"wetGripClass" : "B",
"externalRollingNoise" : 71,
"externalRollingNoiseClass" : "A",
"snowGrip" : true,
"iceGrip" : false,
"version" : 1
} ],
"deposit" : "0.25",
"size" : "small",
"colour" : "yellow",
"gender" : "male",
"material" : "cotton ball",
"replica" : false,
"used" : null,
"condition" : "EXCELLENT",
"conditionType" : "REFURBISHED",
"download" : true,
"dynamicProductAttributes" : {
"22337" : [ "6" ]
}
}
Path parameters
Parameter | Description |
---|---|
|
unique shop identifier |
|
shop unique offer identifier |
Request fields
Field Name | Type | Description | Example | Required for Service | Required for Category |
---|---|---|---|---|---|
|
|
A unique and shop specific identifier which can be chosen freely by the merchant. Please provide it without spaces otherwise, it will be rejected. Please note that this is also used in the URL so the rules for the URL Format apply. Recommendation is to use text only ([A-Z],[a-z],[0-9]) and underscores, dots and dashes. |
|
Price Comparison |
|
|
|
The title of the offer as shown at idealo. The title should contain relevant product attributes and be unique. |
|
Price Comparison |
|
|
|
The price of the offer. Please provide a positive price amount in the format ^d{1,9}.d{2}$. |
|
Price Comparison |
|
|
|
The original price of the offer before any price reduction is applied. The price will not be displayed on idealo.de but is required by us for price comparison purposes. Please provide a positive price amount in the format ^d{1,9}.d{2}$. |
|
Price Comparison |
|
|
|
The URL to the offer page in the merchant’s shop. For the URLs the RFC 3986 standard applies (urls have to start with https:// or http://). For product variants, please use parameterized URLs directing to the respective variant. |
|
Price Comparison |
|
|
|
The price per unit. Required for offers with labeling obligation. |
|
||
|
|
The number of items comprising the offer. Required for multi-packs. |
|
||
|
|
The code of the voucher applicable to the offer. The actual code has to be part of this field. Note: the price field needs to contain a discounted price. |
|
||
|
|
The branch identifier of a shop in order to list an offer as local inventory at idealo. Please ensure that the SKU is globally unique across all branches. If a branchId is set the deliveryCosts must be LOCAL and/or PICKUP. |
|
Required for local inventory offers. |
|
|
|
The name of the brand/manufacturer. Providing the brand is importing for mapping an offer to the idealo product catalog. |
|
||
|
|
The original replacement part number as provided by the car manufacturer. |
|
||
|
|
The offers category in the merchants shop. |
|
||
|
|
A short description of the offer. |
|
||
|
|
A list of image urls for the offer. The first one will be the main picture. Please use standard web formats (png or jpg). The RFC 3986 standard applies. |
|
||
|
|
A list of GTINs / EANs for the offer. |
|
||
|
|
A list of manufacturer article numbers (HANs). Please provide the complete HANs. |
|
||
|
|
A list of "Pharmazentralnummern" (PZNs). Please provide valid PZNs. |
|
||
|
|
A KBA is a unique number that identifies a specific car type at "Kraftfahrt-Bundesamt". Those number consists of HSN and TSN. The KBA is used to identify the correct car spare parts. Please provide a list of valid KBAs for spare parts. |
|
||
|
|
The name of the merchant is necessary if you are a marketplace. The correct merchant’s name. |
|
Price Comparison |
|
|
|
The merchant Id is necessary if you are a marketplace. It has to be a unique identifier. The corresponding unique merchant id. |
|
||
|
|
A list of payment methods and corresponding costs. Costs can be zero (0.00). At least one of CLICK_AND_BUY, CREDIT_CARD, CASH_IN_ADVANCE, CASH_ON_DELIVERY, DIRECT_DEBIT, GOOGLE_CHECKOUT, GIROPAY, INVOICE, MONEYBOOKERS, POSTAL_ORDER, POSTPAY, PAYPAL,PAYSAFECARD, SOFORTUEBERWEISUNG, AMAZON_PAYMENT, ECOTAX, ICLEAR, ELECTRONIC_PAYMENT_STANDARD, BIZUM. |
|
Price Comparison |
|
|
|
A list of delivery types and corresponding costs. At least one of DEUTSCHE_POST, DHL, DHL_EXPRESS, DHL_GO_GREEN, DHL_PACKSTATION, DOWNLOAD, DPD, FEDEX, GERMAN_EXPRESS_LOGISTICS, GLS, GLS_THINK_GREEN, HERMES, PICK_POINT, SPEDITION, TNT, TRANS_O_FLEX, UPS. For offers that are listed as local inventory at least one of LOCAL or PICKUP must be given. |
|
Price Comparison |
|
|
|
Further information about payment / shipping. |
|
||
|
|
Delivery time information for the offer. Please provide precise information. Imprecise phrases like "ready for shipment" or qualifying additions like "presumably" are disallowed. |
|
||
|
|
The maximum number of working days required to prepare the order before shipping. The minimum for this value is 1. Same-day shipping, i.e. a maxOrderProcessingTime of 0, can be implemented by transmitting a maxOrderProcessingTime of 1 and an additional configuration of the cut-off time in idealo business. |
|
||
|
|
The amount of days within free return is granted. |
|
||
|
|
For a better representation of the possible delivery options, it is highly recommended to specify the shipping method. Allowed values: "FREIGHT_FORWARDER", "PARCEL_SERVICE", "DOWNLOAD", "LETTER". |
|
||
|
|
Additional costs incl. VAT for the optional forwarding service "Delivery to the installation site". Please provide the fee in the format ^d{1,9}.d{2}$. Possible values (in EUR) are: |
|
||
|
|
Additional costs incl. VAT for the optional service "old appliance collection". Please provide the fee in the format ^d{1,9}.d{2}$. Possible values (in EUR) are: |
|
||
|
|
The energy label. Deprecated. Please use energyLabels instead. |
|
Required for offers with labeling obligation. |
|
|
|
A list of energy labels. |
|
Required for offers with labeling obligation. |
|
|
|
Classification of the energy consumption according to EU regulations. Required for offers with labeling obligation. |
|
Required for offers with labeling obligation. |
|
|
|
The classification spectrum of the given product-category. Required for offers with labeling obligation. |
|
Required for offers with labeling obligation. |
|
|
|
The applicable fuel efficiency class of the tyre according to Regulation (EU) 2020/740 (letter "A" to "E") |
|
Required for offers for tyres with labeling obligation. |
|
|
|
The applicable wet grip class of the tyre according to Regulation (EU) 2020/740 (letter "A" to "E") |
|
Required for offers for tyres with labeling obligation. |
|
|
|
The external rolling noise measured value (N, in dB(A)) in decibels of the tyre according to Regulation (EU) 2020/740 |
|
Required for offers for tyres with labeling obligation. |
|
|
|
The applicable external rolling noise class of the tyre according to Regulation (EU) 2020/740 (letter "A" to "C") |
|
Required for offers for tyres with labeling obligation. |
|
|
|
Indication of whether the tyre satisfies the minimum snow grip index values set out in UNECE Regulation No 117. |
|
Required for offers for tyres with labeling obligation. |
|
|
|
Indication of whether the tyre satisfies the relevant minimum ice grip index values. |
|
Required for offers for tyres with labeling obligation. |
|
|
|
The image URL of the EEC-label. Please ensure that the image resolution is high enough, so the QR code can be scanned. Required for offers with labeling obligation. |
|
Required for offers with labeling obligation. |
|
|
|
The URL of the EEC datasheet (PDF). Required for offers with labeling obligation. |
|
Required for offers with labeling obligation. |
|
|
|
Optional: This information helps idealo identifying the label version, to ensure that it is displayed correctly. 0 = old label version, 1 = new label version. Null if not applicable or present. |
|
||
|
|
The deposit price. Required for offers with an obligatory deposit fee. Please provide the fee in the format ^d{1,9}.d{2}$. |
|
||
|
|
The offers indication of the size. Please avoid abbreviations (eg. S/M/L) if possible. Please provide separate offers for each size variant. |
|
||
|
|
The offers indication of colour. Please provide separate offers for each colour variant. A colour variant could also be a combination of several colours. |
|
||
|
|
The offers indication of gender, if applicable. Please write out the gender if possible. Please provide separate offers for each gender variant. |
|
||
|
|
The offers indication of material. Required for offers with labeling obligation. Please provide separate offers for each material variant. |
|
||
|
|
Indication whether this offer is a replica (as opposed to original). Allowed values: true / false. Omitting these fields is equivalent to false. |
|
||
|
|
Indication whether this offer is used (as opposed to new). Allowed values: true / false. Omitting these fields is equivalent to false. |
|
||
|
|
Condition of article. Use in combination with |
|
||
|
|
State the article is in. Use in combination with |
|
||
|
|
Indicates whether this offer is downloadable (as opposed to physical goods). Allowed values: true / false. Omitting these fields is equivalent to false. |
|
||
|
|
A list of product attributes specific to this offer (e.g. UK and EU shoe size). This information should help our users to find the offers relevant to their needs. Please provide separate offers for each variant. For a list of possible attribute names, please contact tam@idealo.de. |
|
The response will be as follows:
HTTP response
HTTP/1.1 200 OK
PATCH
Partially updates an offer. In general, requirements stated for PUT do also apply when updating fields with PATCH.
You can only update offers that have been created via a PUT request before. |
For the list fields (type Array) oens, categoryPath, imageUrls, eans, hans, pzns, kbas and energyLabels you can not append additional entries with PATCH. The complete list of entries including those you already sent before is always required. |
The following fields can not be updated by a PATCH request: size, color, gender, material, replica, used, download, deliveryCosts, paymentCosts, dynamicProductAttributes. In order to set these fields, use a PUT request. |
You can not delete single fields with PATCH by setting them to null. Use a PUT for this. |
Example
To update some fields of an existing Offer, for example with a new 'title' and 'price', make the request as below.
Note that we are sending the 'sku' in the body of the request as well. This is necessary otherwise the import will fail. |
HTTP request
PATCH /shop/123/offer/abc3434 HTTP/1.1
Authorization: Bearer <<< OAUTH2_ACCESS_TOKEN_HERE >>>
Content-Type: application/json
Content-Length: 68
Host: localhost:8080
{
"sku" : "abc3434",
"title" : "My Offer",
"price" : "12.80"
}
Path parameters
Parameter | Description |
---|---|
|
unique shop identifier |
|
shop unique offer identifier |
The response will be as follows:
HTTP response
HTTP/1.1 200 OK
DELETE
Deletes an offer.
Example
To delete an Offer, make the following request:
HTTP request
DELETE /shop/123/offer/abc3434 HTTP/1.1
Authorization: Bearer <<< OAUTH2_ACCESS_TOKEN_HERE >>>
Accept: application/json
Host: localhost:8080
Path parameters
Parameter | Description |
---|---|
|
Unique Shop identifier |
|
Unique offer identifier |
The response will be as follows:
HTTP response
HTTP/1.1 200 OK
DELETE All
Delete all existing offers. This is an asynchronous operation. To avoid conflicts, subsequent requests will be rejected with a 409 response until the operation has completed.
Example
To delete all Offers, make the following request:
HTTP request
DELETE /shop/123/offer HTTP/1.1
Authorization: Bearer <<< OAUTH2_ACCESS_TOKEN_HERE >>>
Accept: application/json
Host: localhost:8080
Path parameters
Parameter | Description |
---|---|
|
Unique Shop identifier |
The response will be as follows:
HTTP response
HTTP/1.1 202 Accepted
Change Log
Date | Comment |
---|---|
2024-11-18 |
Included 409 response during delete-all operation |
2024-10-02 |
Added information about new fields: condition and conditionType; deprecated field: used |
2024-09-24 |
Included request size limit information |
2024-09-11 |
Included rate limit information |
2024-04-10 |
Removed UPDATE Timestamp endpoint |
2024-03-04 |
Updated description for formerPrice |
2024-02-07 |
Added information about field: formerPrice |
2023-01-25 |
Deprecated UPDATE Timestamp endpoint |
2023-01-04 |
Removed direct checkout related attributes |
2021-10-19 |
Put example strings in quotes |
2021-09-02 |
Removed field length restrictions from docs |
2021-06-14 |
Added examples of JSON payload in error responses |
2021-04-01 |
Added information about new field: energyLabels |
2021-02-25 |
Added information about new field: dynamicProductAttributes |
2020-04-02 |
Added information about new field: maxOrderProcessingTime |
2020-03-03 |
Added positive price field requirement |
2020-02-11 |
Added authorization headers to request examples |
2019-10-30 |
Removed documentation for lenses and tyres as they cannot be used at the moment |
2019-05-10 |
Added PATCH request section |