General

As a merchant using idealo checkout you can manage your orders via our REST merchant order API v2. This API allows you to synchronize idealo checkout orders with your internal order management system and communicate updates regarding your order status (e.g. completed, revoked, partially revoked) or refund information (orders with idealo checkout payment methods only) towards idealo.

An API method is always called up via HTTPS request. The idealo checkout API will then respond in JSON format.

The base address of the API in production is: https://orders.idealo.com

Announcement

On 31.01.2021 a new status for an order will be released. The new order status REVOKING will be set when idealo receives a revocation request. After the revocation is processed the order status of an order will be set to REVOKED. From now on the getOrders endpoint will accept the order status REVOKING, but will not return any corresponding orders until 31.01.2021.

` Please adjust your API integration to handle the new order status in time! `

idealo business

idealo business as a platform enables merchants to manage their complete business with idealo in self service. For the merchant order API v2 you need the following idealo business features to integrate the API in your system:

  1. Credentials for merchant Order API v2

  2. Test orders and test scenarios

Every shop that is listing on idealo has access to idealo business. If you don’t have an account for idealo business, create one. Therefore you need an invitation. Please get your invitation from any other idealo business user connected to your shop or contact your idealo account manager.

Credentials

To create a clientId and clientSecret you need access to idealo business. There you can create credentials for the merchant order API v2 sandbox and production.

Note
The clientSecret for sandbox and production is only shown once at creation time! If you have no longer access to your clientSecret, please create new credentials.

Authentication

The merchant order API v2 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

  3. Do an order API request

  4. The access token expires after 3600 seconds and you need get a new access token like before.

Sandbox

idealo offers a sandbox for the merchant order API v2 to help merchants integrate the API in their order management system. In the sandbox only test orders for different test scenarios are provided and can be updated by the shop. Payment and refund details are no part of the sandbox.

To access the sandbox, you need sandbox clientId and sandbox clientSecret. As of production: create sandbox OAuth 2.0 Credentials in idealo business

The base address of the API Sandbox is: https://orders-sandbox.idealo.com

Test orders

As soon as you have created your credentials and have access to the sandbox, you can generate test orders in idealo business

Each set of test orders contains 15 different test cases. Please follow the test scenarios while doing the integration.

Currencies

Currently the idealo checkout only supports "EUR" (ISO 4217 currency code) as currency value.

Common mistakes

  • response code 405 (Method Not Allowed) is returned when an unsupported HTTP method is used, for example GET instead of POST

  • response code 415 (Unsupported Media Type) is returned when an unsupported or missing content type header is used, for example a POST request with a json body should set the "Content-Type" header to "application/json"

  • response code 401 (Unauthorized) is returned when an authorization header is missing or the provided credentials are invalid, for example POST "/api/v2/oauth/token" should set the "Authorization" header to "Basic YnVzaW5lc3…​" or GET "/api/v2/shops/{shopId}/new-orders" should set the "Authorization" header to "Bearer eyJraWQiOiJrMSIsImFsZyI…​"

  • call "Get Orders" without paging parameter "pageNumber" and "pageSize" leading to receive just the first page with 1000 orders

Changelog

Date Comments

2019-05-09

  • Initial version

2020-02-28

  • added request headers to documentation

  • added common mistakes section

2020-07-30

  • Refund requests are now validated for the three most common causes of error:

    • the order must have been paid with IDEALO_CHECKOUT_PAYMENTS

    • the order must not be older than 50 days

    • the sum of all refunds must not exceed the total price of the order

      This does not mean that the asynchronous feedback channel is deprecated. There are still edge cases where a refund requests could fail due to payment provider specific issues.

Operations

Get Access Token

POST /api/v2/oauth/token

Returns a jwt access token.

Request headers

Header Type Optional Description

Authorization

Object

false

ClientId and clientSecret as HTTP Basic auth header (e.g. Basic YnVzaW5lc3…​).

Response fields

Path Type Optional Description

access_token

String

true

The access token that is used for authentication.
You need to provide it in the authorization header of all your API requests.

token_type

String

true

The token type. In this case it is bearer.

expires_in

Integer

true

The expiration date of the token. You need to fetch a new token when it is expired.

scope

String

true

The scopes for this token (separated by whitespace).

shop_id

Integer

true

The shopId the access token is valid for.

Example request

$ curl 'https://orders.idealo.com/api/v2/oauth/token' -i -u 'd730802c-2a09-4db6-8bfd-2038f476aca4:clientSecret' -X POST

Example response

HTTP/1.1 200 OK

{
  "access_token" : "jwt access token",
  "token_type" : "bearer",
  "expires_in" : 3600,
  "scope" : "scope",
  "shop_id" : 1
}

Get Orders

GET /api/v2/shops/{shopId}/orders Using this endpoint merchants can filter and get all their orders even if the orders are already completed.
Orders can be filtered by creationDate and status.
The response with all the filtered orders are paginated.
If you only want to get the new orders, please use the endpoint /new-orders.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Id of the shop the orders were made for.

Query parameters

Parameter Type Optional Description

status

Array[Object]

true

Filter orders by a list of status

Allowed values are: (PROCESSING, COMPLETED, REVOKING, REVOKED, PARTIALLY_REVOKED)

from

String

true

The lower limit for the creationDate of the order.

e.g. from=2019-05-01T00:00Z

to

String

true

The upper limit for the creationDate of the order.

e.g. to=2019-05-01T00:00Z

pageNumber

Integer

false

Page number indicates the current page.

Page number starts at 0. If not set, the default page number is 0.

Must be at least 0.

pageSize

Integer

false

Page size indicates how many items are listed on one page.

If not set, the default page size is 1000.

Must be at least 1. Must be at most 1000.

acknowledged

Boolean

true

Filter by state acknowledged. An order is marked as "acknowledged", when the merchant has provided an order number.

Request headers

Header Type Optional Description

Authorization

String

false

Required oauth2 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…​).

Response fields

Path Type Optional Description

content

Array[Object]

true

List of orders.

content[].idealoOrderId

String

true

Id of the order set by idealo
e.g. "ABC1234".

content[].merchantOrderNumber

String

true

Order number or id set by the merchant
e.g. "1234ABC".

content[].created

String

true

Date when order was created (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

content[].updated

String

true

Date when order status was updated (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

content[].status

String

true

Current status of the order.

Must be one of [PROCESSING, COMPLETED, REVOKING, REVOKED, PARTIALLY_REVOKED].

content[].currency

String

true

ISO 4217 currency code.

content[].offersPrice

Decimal

true

Total price of items including VAT, excluding shipping costs value.
e.g. "0.99" "79.99".

content[].grossPrice

Decimal

true

Total amount of the order including VAT and shipping costs.
e.g. "0.99" "79.99".

content[].shippingCosts

Decimal

true

Shipping costs.
e.g. "0.99" "79.99".

content[].lineItems

Array[Object]

true

List of the line items of the order (order positions).

content[].lineItems[].title

String

true

Offer title
e.g. "Example offer title".

content[].lineItems[].price

Decimal

true

Unit price of an item incl. VAT.
e.g. "0.99" "79.99".

content[].lineItems[].formerPrice

Decimal

true

Price before voucher application incl. VAT of an offer.
e.g. "0.99" "79.99".

content[].lineItems[].priceRangeAmount

Decimal

true

Amount by which the offer price was reduced within the price range.
e.g. "0.99" "79.99".

content[].lineItems[].quantity

Integer

true

Amount of items.

content[].lineItems[].sku

String

true

This matches the value provided to idealo as a SKU in the export from a shop
e.g. "product-sku-12345".

content[].lineItems[].merchantId

String

true

Unique identifier of marketplace participant, e.g. id of online shop
e.g. "merchant_12345".

content[].lineItems[].merchantName

String

true

Unique name of marketplace participant, e.g. name of online shop
e.g. "Example Electronics Ltd".

content[].lineItems[].merchantDeliveryText

String

true

Delivery text set by the merchant
e.g. "Delivered within 3 working days".

content[].customer

Object

true

Container for customer information.

content[].customer.email

String

true

Pseudonymised customer email address.

content[].customer.phone

String

true

Customer phone number, only given if fulfillment method "FORWARDING" is chosen
e.g. "030 123 1234" or "030-1231234".

content[].payment

Object

true

Container for payment information.

content[].payment.paymentMethod

String

true

Chosen payment method.

Must be one of [PAYPAL, SOFORT, IDEALO_CHECKOUT_PAYMENTS].

content[].payment.transactionId

String

true

Transaction number used to make payment via payment provider.

content[].billingAddress

Object

true

Container for billing address information.

content[].billingAddress.salutation

String

true

Salutation.

Must be one of [MR, MRS].

content[].billingAddress.firstName

String

true

First name.

content[].billingAddress.lastName

String

true

Last name.

content[].billingAddress.addressLine1

String

true

Street and house number
e.g. "Ritterstraße 11".

content[].billingAddress.addressLine2

String

true

Additional address information
e.g. "c/o idealo".

content[].billingAddress.postalCode

String

true

Postal code or zip code
e.g. "10969".

content[].billingAddress.city

String

true

City
e.g. "Berlin".

content[].billingAddress.countryCode

String

true

Country code (ISO 3166)
e.g. "DE".

content[].shippingAddress

Object

true

Container for shipping address information.

content[].shippingAddress.salutation

String

true

Salutation.

Must be one of [MR, MRS].

content[].shippingAddress.firstName

String

true

First name.

content[].shippingAddress.lastName

String

true

Last name.

content[].shippingAddress.addressLine1

String

true

Street and house number
e.g. "Ritterstraße 11".

content[].shippingAddress.addressLine2

String

true

Additional address information
e.g. "c/o idealo".

content[].shippingAddress.postalCode

String

true

Postal code or zip code
e.g. "10969".

content[].shippingAddress.city

String

true

City
e.g. "Berlin".

content[].shippingAddress.countryCode

String

true

Country code (ISO 3166)
e.g. "DE".

content[].fulfillment

Object

true

Container for fulfillment information.

content[].fulfillment.method

String

true

Chosen fulfillment method.

Must be one of [FORWARDING, LETTER, POSTAL, DOWNLOAD].

content[].fulfillment.tracking

Array[Object]

true

Container for tracking information.

content[].fulfillment.tracking[].code

String

true

Tracking code or tracking number.

content[].fulfillment.tracking[].carrier

String

true

Carrier or shipping company

Common carriers:
"Cargo", "Der Courier", "Deutsche Post", "DHL", "DPD", "eparcel", "FedEx", "GdSK", "GLS", "GO!", "Hermes", "iloxx", "Midway", "Noxxs Logistic", "paket.ag", "primeMail", "TOMBA", "UPS".

content[].fulfillment.options

Array[Object]

true

List of fulfillment options.

content[].fulfillment.options[].forwardOption

String

true

Chosen forwarding option.

Must be one of [TWO_MAN_DELIVERY, PICKUP_SERVICE].

content[].fulfillment.options[].price

Decimal

true

Fulfillment costs.
e.g. "0.99" "79.99".

content[].refunds

Array[Object]

true

List of the refunds of the order.

content[].refunds[].refundId

String

true

Idealo refund id.

content[].refunds[].refundTransactionId

String

true

Transaction id used by the payment provider for the refund.

content[].refunds[].status

String

true

Status of the refund.

Must be one of [OPEN, FAILED, SUCCESS].

content[].refunds[].currency

String

true

ISO 4217 currency code.

content[].refunds[].refundAmount

Decimal

true

Refund amount.

content[].refunds[].failureReason

String

true

Reason text if a refund fails.

content[].refunds[].created

String

true

Date when the refund was created (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

content[].refunds[].updated

String

true

Date of the last update of the refund (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

content[].voucher

Object

true

Container for voucher information.

content[].voucher.code

String

true

Voucher code.
e.g. "FXWFGE (30%, max. 5 EUR)".

totalElements

Integer

true

Total number of available orders.

totalPages

Integer

true

Number of available pages.

Example request

$ curl 'https://orders.idealo.com/api/v2/shops/12345/orders?from=2019-05-01T02%3A00%2B02%3A00&to=2019-05-01T10%3A50%3A00Z&status=PROCESSING&pageNumber=0&pageSize=10&acknowledged=false' -i -X GET \
    -H 'Authorization: Bearer eyJraWQiOiJrMSIsImFsZyI...'

Example response

HTTP/1.1 200 OK

{
  "content" : [ {
    "idealoOrderId" : "A1B2C3D4",
    "merchantOrderNumber" : "1234ABC",
    "created" : "2019-05-01T00:00:00Z",
    "updated" : "2019-05-01T00:00:00Z",
    "status" : "PROCESSING",
    "currency" : "EUR",
    "offersPrice" : "50.85",
    "grossPrice" : "53.84",
    "shippingCosts" : "2.99",
    "lineItems" : [ {
      "title" : "Example offer 1",
      "price" : "30.55",
      "formerPrice" : "31.99",
      "priceRangeAmount" : "1.44",
      "quantity" : 1,
      "sku" : "product-sku-12345",
      "merchantId" : "merchant_12345",
      "merchantName" : "Example Electronics Ltd",
      "merchantDeliveryText" : "Delivered within 3 working days"
    }, {
      "title" : "Example offer 2",
      "price" : "10.15",
      "quantity" : 2,
      "sku" : "product-sku-5648",
      "merchantId" : "merchant_12345",
      "merchantName" : "Example Electronics Ltd",
      "merchantDeliveryText" : "Delivered within 3 working days"
    } ],
    "customer" : {
      "email" : "m-zvvtu596gbz00t0@checkout.idealo.de",
      "phone" : "030-1231234"
    },
    "payment" : {
      "paymentMethod" : "PAYPAL",
      "transactionId" : "acb-123"
    },
    "billingAddress" : {
      "salutation" : "MR",
      "firstName" : "Max",
      "lastName" : "Mustermann",
      "addressLine1" : "Ritterstraße 11",
      "addressLine2" : "c/o idealo",
      "postalCode" : "10969",
      "city" : "Berlin",
      "countryCode" : "DE"
    },
    "shippingAddress" : {
      "salutation" : "MR",
      "firstName" : "Max",
      "lastName" : "Mustermann",
      "addressLine1" : "Ritterstraße 11",
      "addressLine2" : "c/o idealo",
      "postalCode" : "10969",
      "city" : "Berlin",
      "countryCode" : "DE"
    },
    "fulfillment" : {
      "method" : "POSTAL",
      "tracking" : [ {
        "code" : "xyz1234",
        "carrier" : "Cargo"
      } ],
      "options" : [ {
        "forwardOption" : "TWO_MAN_DELIVERY",
        "price" : "2.99"
      } ]
    },
    "refunds" : [ {
      "refundId" : "example-refund-id",
      "refundTransactionId" : "example-refund-transaction-id",
      "status" : "OPEN",
      "currency" : "EUR",
      "refundAmount" : 1.99
    } ],
    "voucher" : {
      "code" : "FXWFGE (30%, max. 5 EUR)"
    }
  } ],
  "totalElements" : 1,
  "totalPages" : 1
}

Get Order

GET /api/v2/shops/{shopId}/orders/{idealoOrderId}

Using this endpoint merchants can get an order by idealoOrderId.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Id of the shop the orders were made for.

idealoOrderId

String

false

Id of the order set by idealo.

Request headers

Header Type Optional Description

Authorization

String

false

Required oauth2 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…​).

Response fields

Path Type Optional Description

idealoOrderId

String

true

Id of the order set by idealo
e.g. "ABC1234".

merchantOrderNumber

String

true

Order number or id set by the merchant
e.g. "1234ABC".

created

String

true

Date when order was created (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

updated

String

true

Date when order status was updated (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

status

String

true

Current status of the order.

Must be one of [PROCESSING, COMPLETED, REVOKING, REVOKED, PARTIALLY_REVOKED].

currency

String

true

ISO 4217 currency code.

offersPrice

Decimal

true

Total price of items including VAT, excluding shipping costs value.
e.g. "0.99" "79.99".

grossPrice

Decimal

true

Total amount of the order including VAT and shipping costs.
e.g. "0.99" "79.99".

shippingCosts

Decimal

true

Shipping costs.
e.g. "0.99" "79.99".

lineItems

Array[Object]

true

List of the line items of the order (order positions).

lineItems[].title

String

true

Offer title
e.g. "Example offer title".

lineItems[].price

Decimal

true

Unit price of an item incl. VAT.
e.g. "0.99" "79.99".

lineItems[].formerPrice

Decimal

true

Price before voucher application incl. VAT of an offer.
e.g. "0.99" "79.99".

lineItems[].priceRangeAmount

Decimal

true

Amount by which the offer price was reduced within the price range.
e.g. "0.99" "79.99".

lineItems[].quantity

Integer

true

Amount of items.

lineItems[].sku

String

true

This matches the value provided to idealo as a SKU in the export from a shop
e.g. "product-sku-12345".

lineItems[].merchantId

String

true

Unique identifier of marketplace participant, e.g. id of online shop
e.g. "merchant_12345".

lineItems[].merchantName

String

true

Unique name of marketplace participant, e.g. name of online shop
e.g. "Example Electronics Ltd".

lineItems[].merchantDeliveryText

String

true

Delivery text set by the merchant
e.g. "Delivered within 3 working days".

customer

Object

true

Container for customer information.

customer.email

String

true

Pseudonymised customer email address.

customer.phone

String

true

Customer phone number, only given if fulfillment method "FORWARDING" is chosen
e.g. "030 123 1234" or "030-1231234".

payment

Object

true

Container for payment information.

payment.paymentMethod

String

true

Chosen payment method.

Must be one of [PAYPAL, SOFORT, IDEALO_CHECKOUT_PAYMENTS].

payment.transactionId

String

true

Transaction number used to make payment via payment provider.

billingAddress

Object

true

Container for billing address information.

billingAddress.salutation

String

true

Salutation.

Must be one of [MR, MRS].

billingAddress.firstName

String

true

First name.

billingAddress.lastName

String

true

Last name.

billingAddress.addressLine1

String

true

Street and house number
e.g. "Ritterstraße 11".

billingAddress.addressLine2

String

true

Additional address information
e.g. "c/o idealo".

billingAddress.postalCode

String

true

Postal code or zip code
e.g. "10969".

billingAddress.city

String

true

City
e.g. "Berlin".

billingAddress.countryCode

String

true

Country code (ISO 3166)
e.g. "DE".

shippingAddress

Object

true

Container for shipping address information.

shippingAddress.salutation

String

true

Salutation.

Must be one of [MR, MRS].

shippingAddress.firstName

String

true

First name.

shippingAddress.lastName

String

true

Last name.

shippingAddress.addressLine1

String

true

Street and house number
e.g. "Ritterstraße 11".

shippingAddress.addressLine2

String

true

Additional address information
e.g. "c/o idealo".

shippingAddress.postalCode

String

true

Postal code or zip code
e.g. "10969".

shippingAddress.city

String

true

City
e.g. "Berlin".

shippingAddress.countryCode

String

true

Country code (ISO 3166)
e.g. "DE".

fulfillment

Object

true

Container for fulfillment information.

fulfillment.method

String

true

Chosen fulfillment method.

Must be one of [FORWARDING, LETTER, POSTAL, DOWNLOAD].

fulfillment.tracking

Array[Object]

true

Container for tracking information.

fulfillment.tracking[].code

String

true

Tracking code or tracking number.

fulfillment.tracking[].carrier

String

true

Carrier or shipping company

Common carriers:
"Cargo", "Der Courier", "Deutsche Post", "DHL", "DPD", "eparcel", "FedEx", "GdSK", "GLS", "GO!", "Hermes", "iloxx", "Midway", "Noxxs Logistic", "paket.ag", "primeMail", "TOMBA", "UPS".

fulfillment.options

Array[Object]

true

List of fulfillment options.

fulfillment.options[].forwardOption

String

true

Chosen forwarding option.

Must be one of [TWO_MAN_DELIVERY, PICKUP_SERVICE].

fulfillment.options[].price

Decimal

true

Fulfillment costs.
e.g. "0.99" "79.99".

refunds

Array[Object]

true

List of the refunds of the order.

refunds[].refundId

String

true

Idealo refund id.

refunds[].refundTransactionId

String

true

Transaction id used by the payment provider for the refund.

refunds[].status

String

true

Status of the refund.

Must be one of [OPEN, FAILED, SUCCESS].

refunds[].currency

String

true

ISO 4217 currency code.

refunds[].refundAmount

Decimal

true

Refund amount.

refunds[].failureReason

String

true

Reason text if a refund fails.

refunds[].created

String

true

Date when the refund was created (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

refunds[].updated

String

true

Date of the last update of the refund (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

voucher

Object

true

Container for voucher information.

voucher.code

String

true

Voucher code.
e.g. "FXWFGE (30%, max. 5 EUR)".

Example request

$ curl 'https://orders.idealo.com/api/v2/shops/12345/orders/A1B2C3D4' -i -X GET \
    -H 'Authorization: Bearer eyJraWQiOiJrMSIsImFsZyI...'

Example response

HTTP/1.1 200 OK

{
  "idealoOrderId" : "A1B2C3D4",
  "merchantOrderNumber" : "1234ABC",
  "created" : "2019-05-01T00:00:00Z",
  "updated" : "2019-05-01T00:00:00Z",
  "status" : "PROCESSING",
  "currency" : "EUR",
  "offersPrice" : "50.85",
  "grossPrice" : "53.84",
  "shippingCosts" : "2.99",
  "lineItems" : [ {
    "title" : "Example offer 1",
    "price" : "30.55",
    "formerPrice" : "31.99",
    "priceRangeAmount" : "1.44",
    "quantity" : 1,
    "sku" : "product-sku-12345",
    "merchantId" : "merchant_12345",
    "merchantName" : "Example Electronics Ltd",
    "merchantDeliveryText" : "Delivered within 3 working days"
  }, {
    "title" : "Example offer 2",
    "price" : "10.15",
    "quantity" : 2,
    "sku" : "product-sku-5648",
    "merchantId" : "merchant_12345",
    "merchantName" : "Example Electronics Ltd",
    "merchantDeliveryText" : "Delivered within 3 working days"
  } ],
  "customer" : {
    "email" : "m-zvvtu596gbz00t0@checkout.idealo.de",
    "phone" : "030-1231234"
  },
  "payment" : {
    "paymentMethod" : "PAYPAL",
    "transactionId" : "acb-123"
  },
  "billingAddress" : {
    "salutation" : "MR",
    "firstName" : "Max",
    "lastName" : "Mustermann",
    "addressLine1" : "Ritterstraße 11",
    "addressLine2" : "c/o idealo",
    "postalCode" : "10969",
    "city" : "Berlin",
    "countryCode" : "DE"
  },
  "shippingAddress" : {
    "salutation" : "MR",
    "firstName" : "Max",
    "lastName" : "Mustermann",
    "addressLine1" : "Ritterstraße 11",
    "addressLine2" : "c/o idealo",
    "postalCode" : "10969",
    "city" : "Berlin",
    "countryCode" : "DE"
  },
  "fulfillment" : {
    "method" : "POSTAL",
    "tracking" : [ {
      "code" : "xyz1234",
      "carrier" : "Cargo"
    } ],
    "options" : [ {
      "forwardOption" : "TWO_MAN_DELIVERY",
      "price" : "2.99"
    } ]
  },
  "refunds" : [ {
    "refundId" : "example-refund-id",
    "refundTransactionId" : "example-refund-transaction-id",
    "status" : "OPEN",
    "currency" : "EUR",
    "refundAmount" : 1.99
  } ],
  "voucher" : {
    "code" : "FXWFGE (30%, max. 5 EUR)"
  }
}

Get New Orders

GET /api/v2/shops/{shopId}/new-orders

Get all new orders for a shopId. New orders are all orders which are not yet acknowledged by the shop (similar to the get orders endpoint in v1) and where the order status is 'PROCESSING'.
An order is marked as "acknowledged", when the merchant has provided an order number.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Id of the shop the orders were made for.

Request headers

Header Type Optional Description

Authorization

String

false

Required oauth2 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…​).

Response fields

Path Type Optional Description

[].idealoOrderId

String

true

Id of the order set by idealo
e.g. "ABC1234".

[].merchantOrderNumber

String

true

Order number or id set by the merchant
e.g. "1234ABC".

[].created

String

true

Date when order was created (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

[].updated

String

true

Date when order status was updated (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

[].status

String

true

Current status of the order.

Must be one of [PROCESSING, COMPLETED, REVOKING, REVOKED, PARTIALLY_REVOKED].

[].currency

String

true

ISO 4217 currency code.

[].offersPrice

Decimal

true

Total price of items including VAT, excluding shipping costs value.
e.g. "0.99" "79.99".

[].grossPrice

Decimal

true

Total amount of the order including VAT and shipping costs.
e.g. "0.99" "79.99".

[].shippingCosts

Decimal

true

Shipping costs.
e.g. "0.99" "79.99".

[].lineItems

Array[Object]

true

List of the line items of the order (order positions).

[].lineItems[].title

String

true

Offer title
e.g. "Example offer title".

[].lineItems[].price

Decimal

true

Unit price of an item incl. VAT.
e.g. "0.99" "79.99".

[].lineItems[].formerPrice

Decimal

true

Price before voucher application incl. VAT of an offer.
e.g. "0.99" "79.99".

[].lineItems[].priceRangeAmount

Decimal

true

Amount by which the offer price was reduced within the price range.
e.g. "0.99" "79.99".

[].lineItems[].quantity

Integer

true

Amount of items.

[].lineItems[].sku

String

true

This matches the value provided to idealo as a SKU in the export from a shop
e.g. "product-sku-12345".

[].lineItems[].merchantId

String

true

Unique identifier of marketplace participant, e.g. id of online shop
e.g. "merchant_12345".

[].lineItems[].merchantName

String

true

Unique name of marketplace participant, e.g. name of online shop
e.g. "Example Electronics Ltd".

[].lineItems[].merchantDeliveryText

String

true

Delivery text set by the merchant
e.g. "Delivered within 3 working days".

[].customer

Object

true

Container for customer information.

[].customer.email

String

true

Pseudonymised customer email address.

[].customer.phone

String

true

Customer phone number, only given if fulfillment method "FORWARDING" is chosen
e.g. "030 123 1234" or "030-1231234".

[].payment

Object

true

Container for payment information.

[].payment.paymentMethod

String

true

Chosen payment method.

Must be one of [PAYPAL, SOFORT, IDEALO_CHECKOUT_PAYMENTS].

[].payment.transactionId

String

true

Transaction number used to make payment via payment provider.

[].billingAddress

Object

true

Container for billing address information.

[].billingAddress.salutation

String

true

Salutation.

Must be one of [MR, MRS].

[].billingAddress.firstName

String

true

First name.

[].billingAddress.lastName

String

true

Last name.

[].billingAddress.addressLine1

String

true

Street and house number
e.g. "Ritterstraße 11".

[].billingAddress.addressLine2

String

true

Additional address information
e.g. "c/o idealo".

[].billingAddress.postalCode

String

true

Postal code or zip code
e.g. "10969".

[].billingAddress.city

String

true

City
e.g. "Berlin".

[].billingAddress.countryCode

String

true

Country code (ISO 3166)
e.g. "DE".

[].shippingAddress

Object

true

Container for shipping address information.

[].shippingAddress.salutation

String

true

Salutation.

Must be one of [MR, MRS].

[].shippingAddress.firstName

String

true

First name.

[].shippingAddress.lastName

String

true

Last name.

[].shippingAddress.addressLine1

String

true

Street and house number
e.g. "Ritterstraße 11".

[].shippingAddress.addressLine2

String

true

Additional address information
e.g. "c/o idealo".

[].shippingAddress.postalCode

String

true

Postal code or zip code
e.g. "10969".

[].shippingAddress.city

String

true

City
e.g. "Berlin".

[].shippingAddress.countryCode

String

true

Country code (ISO 3166)
e.g. "DE".

[].fulfillment

Object

true

Container for fulfillment information.

[].fulfillment.method

String

true

Chosen fulfillment method.

Must be one of [FORWARDING, LETTER, POSTAL, DOWNLOAD].

[].fulfillment.tracking

Array[Object]

true

Container for tracking information.

[].fulfillment.tracking[].code

String

true

Tracking code or tracking number.

[].fulfillment.tracking[].carrier

String

true

Carrier or shipping company

Common carriers:
"Cargo", "Der Courier", "Deutsche Post", "DHL", "DPD", "eparcel", "FedEx", "GdSK", "GLS", "GO!", "Hermes", "iloxx", "Midway", "Noxxs Logistic", "paket.ag", "primeMail", "TOMBA", "UPS".

[].fulfillment.options

Array[Object]

true

List of fulfillment options.

[].fulfillment.options[].forwardOption

String

true

Chosen forwarding option.

Must be one of [TWO_MAN_DELIVERY, PICKUP_SERVICE].

[].fulfillment.options[].price

Decimal

true

Fulfillment costs.
e.g. "0.99" "79.99".

[].refunds

Array[Object]

true

List of the refunds of the order.

[].refunds[].refundId

String

true

Idealo refund id.

[].refunds[].refundTransactionId

String

true

Transaction id used by the payment provider for the refund.

[].refunds[].status

String

true

Status of the refund.

Must be one of [OPEN, FAILED, SUCCESS].

[].refunds[].currency

String

true

ISO 4217 currency code.

[].refunds[].refundAmount

Decimal

true

Refund amount.

[].refunds[].failureReason

String

true

Reason text if a refund fails.

[].refunds[].created

String

true

Date when the refund was created (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

[].refunds[].updated

String

true

Date of the last update of the refund (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

[].voucher

Object

true

Container for voucher information.

[].voucher.code

String

true

Voucher code.
e.g. "FXWFGE (30%, max. 5 EUR)".

Example request

$ curl 'https://orders.idealo.com/api/v2/shops/12345/new-orders' -i -X GET \
    -H 'Authorization: Bearer eyJraWQiOiJrMSIsImFsZyI...'

Example response

HTTP/1.1 200 OK

[ {
  "idealoOrderId" : "A1B2C3D4",
  "merchantOrderNumber" : "1234ABC",
  "created" : "2019-05-01T00:00:00Z",
  "updated" : "2019-05-01T00:00:00Z",
  "status" : "PROCESSING",
  "currency" : "EUR",
  "offersPrice" : "50.85",
  "grossPrice" : "53.84",
  "shippingCosts" : "2.99",
  "lineItems" : [ {
    "title" : "Example offer 1",
    "price" : "30.55",
    "formerPrice" : "31.99",
    "priceRangeAmount" : "1.44",
    "quantity" : 1,
    "sku" : "product-sku-12345",
    "merchantId" : "merchant_12345",
    "merchantName" : "Example Electronics Ltd",
    "merchantDeliveryText" : "Delivered within 3 working days"
  }, {
    "title" : "Example offer 2",
    "price" : "10.15",
    "quantity" : 2,
    "sku" : "product-sku-5648",
    "merchantId" : "merchant_12345",
    "merchantName" : "Example Electronics Ltd",
    "merchantDeliveryText" : "Delivered within 3 working days"
  } ],
  "customer" : {
    "email" : "m-zvvtu596gbz00t0@checkout.idealo.de",
    "phone" : "030-1231234"
  },
  "payment" : {
    "paymentMethod" : "PAYPAL",
    "transactionId" : "acb-123"
  },
  "billingAddress" : {
    "salutation" : "MR",
    "firstName" : "Max",
    "lastName" : "Mustermann",
    "addressLine1" : "Ritterstraße 11",
    "addressLine2" : "c/o idealo",
    "postalCode" : "10969",
    "city" : "Berlin",
    "countryCode" : "DE"
  },
  "shippingAddress" : {
    "salutation" : "MR",
    "firstName" : "Max",
    "lastName" : "Mustermann",
    "addressLine1" : "Ritterstraße 11",
    "addressLine2" : "c/o idealo",
    "postalCode" : "10969",
    "city" : "Berlin",
    "countryCode" : "DE"
  },
  "fulfillment" : {
    "method" : "POSTAL",
    "tracking" : [ {
      "code" : "xyz1234",
      "carrier" : "Cargo"
    } ],
    "options" : [ {
      "forwardOption" : "TWO_MAN_DELIVERY",
      "price" : "2.99"
    } ]
  },
  "refunds" : [ {
    "refundId" : "example-refund-id",
    "refundTransactionId" : "example-refund-transaction-id",
    "status" : "OPEN",
    "currency" : "EUR",
    "refundAmount" : 1.99
  } ],
  "voucher" : {
    "code" : "FXWFGE (30%, max. 5 EUR)"
  }
} ]

Set Merchant Order Number

POST /api/v2/shops/{shopId}/orders/{idealoOrderId}/merchant-order-number

Using this endpoint, merchants can communicate their order numbers to idealo.
After the merchant order number has benn provided, the order will be marked as "acknowledged". This has no effect to the "status" of an order.
The order number cannot be modified, repeated requests will lead to an error.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Id of the shop the orders was made for.

idealoOrderId

String

false

IdealoOrderId of the order for which the order information should be set.

Request fields

Path Type Optional Description

merchantOrderNumber

String

false

The merchant order number.

Must have at least 1 and at most 127 characters.

Request headers

Header Type Optional Description

Authorization

String

false

Required oauth2 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…​).

Content-Type

String

false

Currently supported: "application/json".

Example request

$ curl 'https://orders.idealo.com/api/v2/shops/12345/orders/A1B2C3D4/merchant-order-number' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJraWQiOiJrMSIsImFsZyI...' \
    -d '{"merchantOrderNumber":"my-shops-order-number"}'

Example response

HTTP/1.1 204 No Content

Set Fulfillment Information

POST /api/v2/shops/{shopId}/orders/{idealoOrderId}/fulfillment

Using this endpoint, merchant can update their fulfillment information. This method indicates the order as "sent to the customer" and set the order status to "COMPLETED".

Additionally, tracking information like carrier and tracking codes can be submitted, to enable idealo to track the order and deliver this information to the customer. Tracking information can be extended by submitting carrier and tracking codes multiple time.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Id of the shop the orders was made for.

idealoOrderId

String

false

IdealoOrderId of the order for which the fulfillment information should be set.

Request fields

Path Type Optional Description

carrier

String

true

Shipping company

Common carriers:
"Cargo", "Der Courier", "Deutsche Post", "DHL", "DPD", "eparcel", "FedEx", "GdSK", "GLS", "GO!", "Hermes", "iloxx", "Midway", "Noxxs Logistic", "paket.ag", "primeMail", "TOMBA", "UPS"

If set, a tracking code is mandatory.

Must have at least 1 and at most 31 characters.
must be null or not be blank.

trackingCode

Array[String]

true

Tracking code or tracking number

If set, a carrier is mandatory. Each tracking code must contain at least 1 and at most 127 characters.

must be null or not empty.

Request headers

Header Type Optional Description

Authorization

String

false

Required oauth2 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…​).

Content-Type

String

false

Currently supported: "application/json".

Example request

$ curl 'https://orders.idealo.com/api/v2/shops/12345/orders/A1B2C3D4/fulfillment' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJraWQiOiJrMSIsImFsZyI...' \
    -d '{"carrier":"DHL","trackingCode":["example-tracking-number-1234"]}'

Example response

HTTP/1.1 201 Created

Revoke Order

POST /api/v2/shops/{shopId}/orders/{idealoOrderId}/revocations

Using this endpoint, merchants can revoke orders. If an order is revoked a reason for the revocation is mandatory (e.g. merchant decline, customer revoke, etc…​). A revocation does not automatically triggers a refund. Therefore use the refund endpoint to refund it.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Id of the shop the order was made for.

idealoOrderId

String

false

IdealoOrderId of the order that has to be revoked.

Request fields

Path Type Optional Description

sku

String

false

Sku of the order line item that should be revoked.

remainingQuantity

Integer

true

Number of remaining items for the given SKU.

If not set, then all items of the given SKU will be revoked.

Must be positive or zero.

reason

String

false

Reason for revocation.

Must be one of [MERCHANT_DECLINE, CUSTOMER_REVOKE, RETOUR].

comment

String

true

Comment about revocation.

Value of parameter 'comment' too long.

Request headers

Header Type Optional Description

Authorization

String

false

Required oauth2 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…​).

Content-Type

String

false

Currently supported: "application/json".

Example request

$ curl 'https://orders.idealo.com/api/v2/shops/12345/orders/A1B2C3D4/revocations' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJraWQiOiJrMSIsImFsZyI...' \
    -d '{"sku":"1x2y3z","remainingQuantity":0,"reason":"MERCHANT_DECLINE","comment":"a comment"}'

Example response

HTTP/1.1 204 No Content

Revoke Order (deprecated)

POST /api/v2/shops/{shopId}/orders/{idealoOrderId}/items/{sku}/revocations

Deprecated. Use Revoke Order (POST /api/v2/shops/{shopId}/orders/{idealoOrderId}/revocations).

Using this endpoint, merchants can revoke orders. If an order is revoked a reason for the revocation is mandatory (e.g. merchant decline, customer revoke, etc…​). A revocation does not automatically triggers a refund. Therefore use the refund endpoint to refund it.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Id of the shop the order was made for.

idealoOrderId

String

false

IdealoOrderId of the order that has to be revoked.

sku

String

false

Sku of the order line item.

Request fields

Path Type Optional Description

remainingQuantity

Integer

true

Number of remaining items for the given SKU.

If not set, then all items of the given SKU will be revoked.

Must be positive or zero.

reason

String

false

Reason for revocation.

Must be one of [MERCHANT_DECLINE, CUSTOMER_REVOKE, RETOUR].

comment

String

true

Comment about revocation.

Value of parameter 'comment' too long.

Request headers

Header Type Optional Description

Authorization

String

false

Required oauth2 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…​).

Content-Type

String

false

Currently supported: "application/json".

Example request

$ curl 'https://orders.idealo.com/api/v2/shops/12345/orders/A1B2C3D4/items/1x2y3z/revocations' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJraWQiOiJrMSIsImFsZyI...' \
    -d '{"remainingQuantity":0,"reason":"MERCHANT_DECLINE","comment":"a comment"}'

Example response

HTTP/1.1 204 No Content

Refund Order

POST /api/v2/shops/{shopId}/orders/{idealoOrderId}/refunds

Using this endpoint merchants can refund orders that have been payed with idealo checkout payments only. Orders with a different payment must be refunded by the merchant directly. A refund does not automatically mean that the order is revoked. For revocation the API provides a separate endpoint. It is also possible to refund orders without placing a revocation (e.g. good will). If you are not using idealo checkout payment methods you do not have to implements this endpoint.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Id of the shop the orders was made for.

idealoOrderId

String

false

IdealoOrderId of the order that has to be refunded.

Request fields

Path Type Optional Description

refundAmount

Decimal

false

The amount you want to refund.
e.g. "0.99" "99999.99".

Invalid refund amount format.
Must be at least 0.01.

currency

String

false

ISO 4217 currency code. Currently only "EUR" is allowed.

Request headers

Header Type Optional Description

Authorization

String

false

Required oauth2 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…​).

Content-Type

String

false

Currently supported: "application/json".

Example request

$ curl 'https://orders.idealo.com/api/v2/shops/12345/orders/A1B2C3D4/refunds' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJraWQiOiJrMSIsImFsZyI...' \
    -d '{"refundAmount":35.69,"currency":"EUR"}'

Example response

HTTP/1.1 202 Accepted

Example response for invalid requests

HTTP/1.1 400 Bad Request

{
  "type" : "about:blank",
  "title" : "This order is not refundable as it was not paid using 'IDEALO_CHECKOUT_PAYMENTS'.",
  "instance" : "https://orders.idealo.com/api/v2/shops/12345/orders/A1B2C3D4/refunds",
  "reason" : "ORDER_NOT_PAID_USING_IDEALO_CHECKOUT_PAYMENTS"
}
Reason Description

ORDER_NOT_PAID_USING_IDEALO_CHECKOUT_PAYMENTS

Occurs if the order has not been paid with IDEALO_CHECKOUT_PAYMENTS

REFUND_PERIOD_EXCEEDED

Occurs if the order is older than 50 days.

REFUND_AMOUNT_EXCEEDS_ORDER_PRICE

Occurs if the sum of all refunds exceeds the total price of the order

Get Refunds

GET /api/v2/shops/{shopId}/orders/{idealoOrderId}/refunds

Using this endpoint merchants can get all refunds for a specified order that have been payed with idealo checkout payment methods only.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Id of the shop the orders was made for.

idealoOrderId

String

false

IdealoOrderId of the order that has been refunded.

Request headers

Header Type Optional Description

Authorization

String

false

Required oauth2 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…​).

Response fields

Path Type Optional Description

[].refundId

String

true

Idealo refund id.

[].refundTransactionId

String

true

Transaction id used by the payment provider for the refund.

[].status

String

true

Status of the refund.

Must be one of [OPEN, FAILED, SUCCESS].

[].currency

String

true

ISO 4217 currency code.

[].refundAmount

Decimal

true

Refund amount.

[].failureReason

String

true

Reason text if a refund fails.

[].created

String

true

Date when the refund was created (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

[].updated

String

true

Date of the last update of the refund (ISO 8601, UTC timezone)
e.g. "2019-05-01T00:00:00.000Z".

Example request

$ curl 'https://orders.idealo.com/api/v2/shops/12345/orders/A1B2C3D4/refunds' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJraWQiOiJrMSIsImFsZyI...'

Example response

HTTP/1.1 200 OK

[ {
  "refundId" : "refundId",
  "refundTransactionId" : "refundTransactionId",
  "status" : "SUCCESS",
  "currency" : "EUR",
  "refundAmount" : 1.99,
  "updated" : "2020-09-29T15:37:29.813258Z"
} ]