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:

  1. Obtain OAuth 2.0 Credentials from idealo Business

  2. Obtain an Access Token from the Authorization Server

  3. Do a PWS request

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

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

generalErrors[]

Array

A list of strings, which are human readable general validation errors that does not apply to a particular field

fieldErrors[]

Array

A list of objects, which describe field specific validation errors

fieldErrors[].field

String

Name of the field that was erroneous

fieldErrors[].message

String

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

{
  "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

{
  "fieldErrors" : [ {
    "field" : "price",
    "message" : "Price has has to be provided in format ^\\d{1,9}\\.\\d{2}$"
  } ],
  "generalErrors" : [ ]
}

Resource types

Offer Resource

Allows storage and retrieval of Offers for a given Shop

For generating client for the Offer API, a JSON Schema is available here

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
Path parameters
Table 1. /shop/{shopId}/offer/{sku}
Parameter Description

shopId

Unique shop identifier

sku

Unique offer identifier

The response will be as follows:

HTTP response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "sku" : "ABC13222",
  "title" : "title",
  "price" : "12.80",
  "formerPrice" : "14.80",
  "url" : "http://www.idealo.de/",
  "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" : [ "http://cdn.philips-hue-weiss-und-farbig-10w-e27.jpg", "http://cdn.produktbild_max/philips-hue-schwarz-10w-e27.jpg" ],
  "eans" : [ "5021851148742", "9484474842987" ],
  "hans" : [ "DMC-TZ10EB-K", "DMC-AB567C-J" ],
  "pzns" : [ "03919011", "06893269" ],
  "kbas" : [ "46988 205/55R16" ],
  "merchantName" : "Example merchant",
  "merchantId" : "123456",
  "paymentCosts" : {
    "PAYPAL" : "1.23",
    "INVOICE" : "0.00",
    "CREDIT_CARD" : "2.99",
    "CASH_IN_ADVANCE" : "0.00"
  },
  "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.link.to/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" ]
  }
}

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 >>>

{
  "sku" : "abc3434",
  "title" : "My Offer",
  "price" : "12.80",
  "formerPrice" : "14.80",
  "url" : "http://www.bla.eu",
  "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" : [ "http://cdn.philips-hue-weiss-und-farbig-10w-e27.jpg", "http://cdn.produktbild_max/philips-hue-schwarz-10w-e27.jpg" ],
  "eans" : [ "5021851148742", "9484474842987" ],
  "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.link.to/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" : true,
  "download" : true,
  "dynamicProductAttributes" : {
    "22337" : [ "6" ]
  }
}
Path parameters
Table 1. /shop/{shopId}/offer/{sku}
Parameter Description

shopId

unique shop identifier

sku

shop unique offer identifier

Request fields
Field Name Type Description Example Required for Service Required for Category

sku

String

A unique and shop specific identifier which can be chosen freely by the merchant. Please provide it without any spaces otherwise, it will be filtered and not be visible at idealo frontend. 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.

"ABC-1322-2-17"

Price Comparison

title

String

The title of the offer as shown at idealo. The title should contain relevant product attributes and be unique.

"Canada Goose Carson down-jacket men, navy blue, Size: XXL"

Price Comparison

price

String

The price of the offer. Please provide a positive price amount in the format ^d{1,9}.d{2}$.

"177.99"

Price Comparison

formerPrice

String

The original price of the offer before any price reduction is applied. The price will not be displayed on idealo.de but it can be used in combination with vouchers as information for the merchant. Please provide a positive price amount in the format ^d{1,9}.d{2}$.

"197.99"

Price Comparison

url

String

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.

"http://www.myOffer.eu"

Price Comparison

basePrice

String

The price per unit. Required for offers with labeling obligation.

"1,99€ / 100g"

packagingUnit

Number

The number of items comprising the offer. Required for multi-packs.

5

voucherCode

String

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.

"CAR10 (10% discount for any articles of the category tyres until Dec 31st!)"

branchId

String

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.

"some-id-identifying-your-branch"

Required for local inventory offers.

brand

String

The name of the brand/manufacturer. Providing the brand is importing for mapping an offer to the idealo product catalog.

"Sony"

oens

Array

The original replacement part number as provided by the car manufacturer.

["VW,123 615 301", "BMW,876 647 9879"]

categoryPath

Array

The offers category in the merchants shop.

["Clothes, Shoes & Accessories > Men's Clothing > Shorts", "Men's Outdoor > Shorts"]

description

String

A short description of the offer.

"Digital Camera EOS D5300 with 24 MP and optical Image stabilization, including telephoto lens"

imageUrls

Array

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.

["cdn.philips-hue-weiss-und-farbig-10w-e27.jpg", "cdn.produktbild_max/philips-hue-schwarz-10w-e27.jpg"]

eans

Array

A list of GTINs / EANs for the offer.

["5021851148742", "9484474842987"]

hans

Array

A list of manufacturer article numbers (HANs). Please provide the complete HANs.

["DMC-TZ10EB-K", "DMC-AB567C-J"]

pzns

Array

A list of "Pharmazentralnummern" (PZNs). Please provide valid PZNs.

["03919011", "06893269"]

kbas

Array

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.

["46988 205/55R16"]

merchantName

String

The name of the merchant is necessary if you are a marketplace. The correct merchant’s name.

"Example merchant"

Price Comparison

merchantId

String

The merchant Id is necessary if you are a marketplace. It has to be a unique identifier. The corresponding unique merchant id.

"12345" or "merchant12x"

paymentCosts

Object

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.

{"CASH_IN_ADVANCE": "0.00", "PAYPAL": "1.23", "INVOICE": "0.00", "CREDIT_CARD": "2.99"}

Price Comparison

deliveryCosts

Object

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.

{"DHL": "4.90", "FEDEX": "6.90", "SPEDITION": "20.00"}

Price Comparison

deliveryComment

String

Further information about payment / shipping.

"Store pickup possible", "Shipping includes waste disposal"

delivery

String

Delivery time information for the offer. Please provide precise information. Imprecise phrases like "ready for shipment" or qualifying additions like "presumably" are disallowed.

"1-3 working days"

maxOrderProcessingTime

Number

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.

1

freeReturnDays

Number

The amount of days within free return is granted.

14

fulfillmentType

String

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".

"FREIGHT_FORWARDER"

twoManHandlingFee

String

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:
- If "delivery to the installation site" is possible and free of charge, then the value 0.00 should be entered in this field.
- If costs are incurred for "delivery to the installation site", then the corresponding numerical value must be entered.
- If this field is left blank, it is assumed that the option "delivery to the installation site" is not applicable.

"20.00"

disposalFee

String

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:
- If "old appliance collection" is possible and free of charge, then the value 0.00 is to be entered in this field.
- If costs are incurred for the "old appliance collection", then the corresponding numerical value is to be entered.
- If this field is left blank, it is assumed that the option "old appliance collection" is not applicable.

"3.79"

eec

String

The energy label. Deprecated. Please use energyLabels instead.

"A+"+

Required for offers with labeling obligation.

energyLabels[]

Array

A list of energy labels.

[{ "efficiencyClass":"A","spectrum":"A-G","labelUrl":"http://www.link.to/label.jpg","dataSheetUrl":"http://www.example.com/datasheet.pdf","version":1}]

Required for offers with labeling obligation.

energyLabels[].efficiencyClass

String

Classification of the energy consumption according to EU regulations. Required for offers with labeling obligation.
Allowed values if energyLabels[].version=1: A, B, C, D, E, F, G
Allowed values if energyLabels[].version=0: A+++, A++, A+, A, B, C, D, E, F, G

"A"

Required for offers with labeling obligation.

energyLabels[].spectrum

String

The classification spectrum of the given product-category. Required for offers with labeling obligation.
Allowed values if energyLabels[].version=1: A, B, C, D, E, F, G
Allowed values if energyLabels[].version=0: A+++, A++, A+, A, B, C, D, E, F, G
For a range: separated with - (minus)

"A-G"

Required for offers with labeling obligation.

energyLabels[].fuelEfficiencyClass

String

The applicable fuel efficiency class of the tyre according to Regulation (EU) 2020/740 (letter "A" to "E")

"A"

Required for offers for tyres with labeling obligation.

energyLabels[].wetGripClass

String

The applicable wet grip class of the tyre according to Regulation (EU) 2020/740 (letter "A" to "E")

"B"

Required for offers for tyres with labeling obligation.

energyLabels[].externalRollingNoise

Number

The external rolling noise measured value (N, in dB(A)) in decibels of the tyre according to Regulation (EU) 2020/740

71

Required for offers for tyres with labeling obligation.

energyLabels[].externalRollingNoiseClass

String

The applicable external rolling noise class of the tyre according to Regulation (EU) 2020/740 (letter "A" to "C")

"B"

Required for offers for tyres with labeling obligation.

energyLabels[].snowGrip

Boolean

Indication of whether the tyre satisfies the minimum snow grip index values set out in UNECE Regulation No 117.

true

Required for offers for tyres with labeling obligation.

energyLabels[].iceGrip

Boolean

Indication of whether the tyre satisfies the relevant minimum ice grip index values.

false

Required for offers for tyres with labeling obligation.

energyLabels[].labelUrl

String

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.

"http://www.link.to/label.jpg"

Required for offers with labeling obligation.

energyLabels[].dataSheetUrl

String

The URL of the EEC datasheet (PDF). Required for offers with labeling obligation.

"http://www.example.com/datasheet.pdf"

Required for offers with labeling obligation.

energyLabels[].version

Number

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.

1

deposit

String

The deposit price. Required for offers with an obligatory deposit fee. Please provide the fee in the format ^d{1,9}.d{2}$.

"20.00"

size

String

The offers indication of the size. Please avoid abbreviations (eg. S/M/L) if possible. Please provide separate offers for each size variant.

"medium", "52", "XL"

colour

String

The offers indication of colour. Please provide separate offers for each colour variant. A colour variant could also be a combination of several colours.

"red", "yellow/black"

gender

String

The offers indication of gender, if applicable. Please write out the gender if possible. Please provide separate offers for each gender variant.

"female", "male"

material

String

The offers indication of material. Required for offers with labeling obligation. Please provide separate offers for each material variant.

"80% cotton, 20% polyester"

replica

Boolean

Indication whether this offer is a replica (as opposed to original). Allowed values: true / false. Omitting these fields is equivalent to false.

true

used

Boolean

Indication whether this offer is used (as opposed to new). Allowed values: true / false. Omitting these fields is equivalent to false.

true

download

Boolean

Indicates whether this offer is downloadable (as opposed to physical goods). Allowed values: true / false. Omitting these fields is equivalent to false.

true

dynamicProductAttributes

Object

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.

{ "22337": ["6"], "19326": ["39"] }

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
Content-Type: application/json
Authorization: Bearer <<< OAUTH2_ACCESS_TOKEN_HERE >>>

{
  "sku" : "abc3434",
  "title" : "My Offer",
  "price" : "12.80"
}
Path parameters
Table 1. /shop/{shopId}/offer/{sku}
Parameter Description

shopId

unique shop identifier

sku

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
Path parameters
Table 1. /shop/{shopId}/offer/{sku}
Parameter Description

shopId

Unique Shop identifier

sku

Unique offer identifier

The response will be as follows:

HTTP response
HTTP/1.1 200 OK

DELETE All

Delete all existing offers.

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
Path parameters
Table 1. /shop/{shopId}/offer
Parameter Description

shopId

Unique Shop identifier

The response will be as follows:

HTTP response
HTTP/1.1 202 Accepted

[DEPRECATED] UPDATE Timestamp

Updating the import timestamp for all offers

Example

To update the import timestamp for all offers, make the following request:

HTTP request
PUT /shop/123/offer HTTP/1.1
Authorization: Bearer <<< OAUTH2_ACCESS_TOKEN_HERE >>>
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Path parameters
Table 1. /shop/{shopId}/offer
Parameter Description

shopId

Unique Shop identifier

The response will be as follows:

HTTP response
HTTP/1.1 204 No Content

Change Log

Date Comment

2024-02-07

Add formerPrice to attributes

2023-01-25

Deprecate UPDATE Timestamp endpoint

2023-01-04

Remove 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