idealo order API 2.0 documentation

General

As a merchant using idealo checkout you can manage your orders via our REST order API. This API allows you to synchronize idealo checkout orders with your 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 and the API will then respond in JSON format.

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

idealo Business

idealo Business as a platform enables merchants to manage and monitor their cooperation with idealo (dashboards, configurations, statistics, reports…). In order to use the merchant order API you need to create in idealo Business some credentials and to test the integration you can generate some test orders and test scenarios.

All our partners have access to idealo Business. If you don’t have an account yet, please contact your idealo account manager or if an employee of your company already has an account, he is able to invite you as well (under My idealo > Settings).

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 OAuth 2.0. At a high level, you follow four steps:

Obtain OAuth 2.0 Credentials from idealo business
Obtain an access token
Do an order API request
The access token expires after a certain time. Make sure you obtain a new access token when it is about to expire.

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 cannot be fully tested in the sandbox. All triggered refunds are always acknowledged with an error.

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. Test orders can only be generated if offers have been uploaded to the shop as the test orders are generated based on existing offers.

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
2021-04-22	changed refund period for orders to 30 days if the order has been in the state `COMPLETED`
2021-04-06	added new order status `REVOKING`
2021-01-18	added new field `lineItems[].coSponsoringAmount`: Amount by which the offer price was reduced by idealo according to the cosponsoring agreement
2020-07-30	Refund requests are now validated for the three most common causes of error: the order must have been paid by IDEALO_CHECKOUT_PAYMENTS the order must not be older than 60 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.
2020-02-28	added request headers to documentation added common mistakes section
2019-05-09	Initial version

Operations

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…).

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 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. Note that the expiration time may not always be 3600 seconds. Therefore, you should use this field to determine when to renew the token.
scope	String	true	The scopes for this token (separated by whitespace).
shop_id	Integer	true	The shopId the access token is valid for.

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 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. Note that the expiration time may not always be 3600 seconds. Therefore, you should use this field to determine when to renew the token.

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. This endpoint is mandatory if you want to handle orders with status REVOKING.
The response with all filtered orders are paginated and sorted by created date (desc).
Please make sure that pageNumber and pageSize are always set.

For example, if you only want to get new orders, please use the following filter:
?status=PROCESSING&acknowledged=false&pageNumber=0&pageSize=100
To get all revoking, revoked or partially revoked orders, please use the following filter:
?status=REVOKING,REVOKED,PARTIALLY_REVOKED&pageNumber=0&pageSize=100
.

Path parameters

Parameter	Type	Optional	Description
shopId	Integer	false	Id of the shop the orders were made for.

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. If not set, all status are selected.
from	String	true	The lower limit for the creationDate of the order. e.g. from=2019-05-01T00:00:00Z
to	String	true	The upper limit for the creationDate of the order. e.g. to=2019-05-01T00:00: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.

Parameter

Type

Optional

Description

status

Array[Object]

true

Filter orders by a list of status

Allowed values are: PROCESSING, COMPLETED, REVOKING, REVOKED, PARTIALLY_REVOKED.

If not set, all status are selected.

from

String

true

The lower limit for the creationDate of the order.

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

String

true

The upper limit for the creationDate of the order.

e.g. to=2019-05-01T00:00: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 OAuth 2.0 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…).

Header

Type

Optional

Description

Authorization

String

false

Required OAuth 2.0 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 in your online shop before a voucher price reduction. The value has to be provided in your offer import (csv feed or PWS for example). 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" "12.99".
content[].lineItems[].coSponsoringAmount	Decimal	true	Amount by which the offer price was reduced by idealo according to the cosponsoring agreement. e.g. "0.99" "12.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, 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.

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 in your online shop before a voucher price reduction. The value has to be provided in your offer import (csv feed or PWS for example).
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" "12.99".

content[].lineItems[].coSponsoringAmount

Decimal

true

Amount by which the offer price was reduced by idealo according to the cosponsoring agreement.
e.g. "0.99" "12.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, 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=2021-01-01T02%3A00%2B02%3A00&to=2021-01-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" : "2021-01-01T00:00:00Z",
    "updated" : "2021-01-01T00:00:00Z",
    "status" : "PROCESSING",
    "currency" : "EUR",
    "offersPrice" : "50.85",
    "grossPrice" : "53.84",
    "shippingCosts" : "2.99",
    "lineItems" : [ {
      "title" : "Example product 1",
      "price" : "30.55",
      "priceRangeAmount" : "1.44",
      "quantity" : 1,
      "sku" : "product-sku-12345",
      "merchantId" : "merchant_12345",
      "merchantName" : "Example Electronics Ltd",
      "merchantDeliveryText" : "Delivered within 3 working days"
    }, {
      "title" : "Example product 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" : "IDEALO_CHECKOUT_PAYMENTS",
      "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" : "FORWARDING",
      "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,
      "created" : "2021-05-03T12:03:26.091295Z",
      "updated" : "2021-05-03T12:03:26.091295Z"
    } ],
    "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.

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 OAuth 2.0 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…).

Header

Type

Optional

Description

Authorization

String

false

Required OAuth 2.0 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 in your online shop before a voucher price reduction. The value has to be provided in your offer import (csv feed or PWS for example). 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" "12.99".
lineItems[].coSponsoringAmount	Decimal	true	Amount by which the offer price was reduced by idealo according to the cosponsoring agreement. e.g. "0.99" "12.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, 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)".

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 in your online shop before a voucher price reduction. The value has to be provided in your offer import (csv feed or PWS for example).
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" "12.99".

lineItems[].coSponsoringAmount

Decimal

true

Amount by which the offer price was reduced by idealo according to the cosponsoring agreement.
e.g. "0.99" "12.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, 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

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" : "2021-01-01T00:00:00Z",
  "updated" : "2021-01-01T00:00:00Z",
  "status" : "PROCESSING",
  "currency" : "EUR",
  "offersPrice" : "50.85",
  "grossPrice" : "53.84",
  "shippingCosts" : "2.99",
  "lineItems" : [ {
    "title" : "Example product 1",
    "price" : "30.55",
    "priceRangeAmount" : "1.44",
    "quantity" : 1,
    "sku" : "product-sku-12345",
    "merchantId" : "merchant_12345",
    "merchantName" : "Example Electronics Ltd",
    "merchantDeliveryText" : "Delivered within 3 working days"
  }, {
    "title" : "Example product 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" : "IDEALO_CHECKOUT_PAYMENTS",
    "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" : "FORWARDING",
    "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,
    "created" : "2021-05-03T12:03:26.338319Z",
    "updated" : "2021-05-03T12:03:26.338320Z"
  } ],
  "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'.
This endpoint is optional and you should use the endpoint /orders with following filter instead: status=PROCESSING and acknowledged=false.
With this endpoint you cannot handle orders with the new order status REVOKING.
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.

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 OAuth 2.0 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…).

Header

Type

Optional

Description

Authorization

String

false

Required OAuth 2.0 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 in your online shop before a voucher price reduction. The value has to be provided in your offer import (csv feed or PWS for example). 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" "12.99".
[].lineItems[].coSponsoringAmount	Decimal	true	Amount by which the offer price was reduced by idealo according to the cosponsoring agreement. e.g. "0.99" "12.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, 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)".

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 in your online shop before a voucher price reduction. The value has to be provided in your offer import (csv feed or PWS for example).
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" "12.99".

[].lineItems[].coSponsoringAmount

Decimal

true

Amount by which the offer price was reduced by idealo according to the cosponsoring agreement.
e.g. "0.99" "12.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, 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

[].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" : "2021-01-01T00:00:00Z",
  "updated" : "2021-01-01T00:00:00Z",
  "status" : "PROCESSING",
  "currency" : "EUR",
  "offersPrice" : "50.85",
  "grossPrice" : "53.84",
  "shippingCosts" : "2.99",
  "lineItems" : [ {
    "title" : "Example product 1",
    "price" : "30.55",
    "priceRangeAmount" : "1.44",
    "quantity" : 1,
    "sku" : "product-sku-12345",
    "merchantId" : "merchant_12345",
    "merchantName" : "Example Electronics Ltd",
    "merchantDeliveryText" : "Delivered within 3 working days"
  }, {
    "title" : "Example product 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" : "IDEALO_CHECKOUT_PAYMENTS",
    "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" : "FORWARDING",
    "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,
    "created" : "2021-05-03T12:03:25.957007Z",
    "updated" : "2021-05-03T12:03:25.957007Z"
  } ],
  "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 been 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.

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.

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 OAuth 2.0 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…).
Content-Type	String	false	Currently supported: "application/json".

Header

Type

Optional

Description

Authorization

String

false

Required OAuth 2.0 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 should 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.

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.

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 OAuth 2.0 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…).
Content-Type	String	false	Currently supported: "application/json".

Header

Type

Optional

Description

Authorization

String

false

Required OAuth 2.0 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 trigger a refund. In order to refund an order please use the refund endpoint.

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.

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. Maximum length of the comment is 255 characters.

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.

Maximum length of the comment is 255 characters.

Request headers

Header	Type	Optional	Description
Authorization	String	false	Required OAuth 2.0 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…).
Content-Type	String	false	Currently supported: "application/json".

Header

Type

Optional

Description

Authorization

String

false

Required OAuth 2.0 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":"product-sku-12345","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

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.

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. Maximum length of the comment is 255 characters.

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.

Maximum length of the comment is 255 characters.

Request headers

Header	Type	Optional	Description
Authorization	String	false	Required OAuth 2.0 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…).
Content-Type	String	false	Currently supported: "application/json".

Header

Type

Optional

Description

Authorization

String

false

Required OAuth 2.0 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/product-sku-12345/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 paid by idealo checkout payments only. Orders with a different payment method 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 implement 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.

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.

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 OAuth 2.0 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…).
Content-Type	String	false	Currently supported: "application/json".

Header

Type

Optional

Description

Authorization

String

false

Required OAuth 2.0 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":1.99,"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 by IDEALO_CHECKOUT_PAYMENTS
REFUND_PERIOD_EXCEEDED	Occurs if the order is older than 30 days and has been in the state COMPLETED.
REFUND_AMOUNT_EXCEEDS_ORDER_PRICE	Occurs if the sum of all refunds exceeds the total price of the order

Reason

Description

ORDER_NOT_PAID_USING_IDEALO_CHECKOUT_PAYMENTS

Occurs if the order has not been paid by IDEALO_CHECKOUT_PAYMENTS

REFUND_PERIOD_EXCEEDED

Occurs if the order is older than 30 days and has been in the state COMPLETED.

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 paid by 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.

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 OAuth 2.0 access token (e.g. Bearer eyJraWQiOiJrMSIsImFsZyI…).

Header

Type

Optional

Description

Authorization

String

false

Required OAuth 2.0 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".

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" : "example-refund-id",
  "refundTransactionId" : "example-refund-transaction-id",
  "status" : "OPEN",
  "currency" : "EUR",
  "refundAmount" : 1.99,
  "created" : "2021-05-03T12:02:55.363462Z",
  "updated" : "2021-05-03T12:02:55.363462Z"
} ]

idealo order API 2.0 documentation

General

idealo Business

Credentials

Authentication

Sandbox

Test orders

Currencies

Common mistakes

Changelog

Operations

Get Access Token

Request headers

Response fields

Example request

Example response

Get Orders

Path parameters

Query parameters

Request headers

Response fields

Example request

Example response

Get Order

Path parameters

Request headers

Response fields

Example request

Example response

Get New Orders

Path parameters

Request headers

Response fields

Example request

Example response

Set Merchant Order Number

Path parameters

Request fields

Request headers

Example request

Example response

Set Fulfillment Information

Path parameters

Request fields

Request headers

Example request

Example response

Revoke Order

Path parameters

Request fields

Request headers

Example request

Example response

Revoke Order (deprecated)

Path parameters

Request fields

Request headers

Example request

Example response

Refund Order

Path parameters

Request fields

Request headers

Example request

Example response

Example response for invalid requests

Get Refunds

Path parameters

Request headers

Response fields

Example request

Example response