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. The sandbox idealoOrderId are prefixed with two '0', for example: '007K2F4QWF'.
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 |
---|---|
2022-04-07 |
|
2021-11-30 |
improve documentation of |
2021-10-19 |
added new field |
2021-09-08 |
increase allowed refund period for orders to 60 days |
2021-04-22 |
changed refund period for orders to 30 days if the order has been in the state |
2021-04-06 |
added new order status |
2021-01-18 |
added new field |
2020-07-30 |
|
2020-02-28 |
|
2019-05-09 |
|
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. |
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. |
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 processed date of the order. e.g. from=2019-05-01T00:00:00Z |
to |
String |
true |
The upper limit for the processed date 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…). |
Response fields
Path | Type | Optional | Description |
---|---|---|---|
content |
Array[Object] |
true |
List of orders. |
content[].idealoOrderId |
String |
true |
Id of the order set by idealo |
content[].merchantOrderNumber |
String |
true |
Order number or id set by the merchant |
content[].created |
String |
true |
Date when the order was created (ISO 8601, UTC timezone). |
content[].processed |
String |
true |
Date when the order was paid (ISO 8601, UTC timezone). |
content[].updated |
String |
true |
Date when the order status was updated (ISO 8601, UTC timezone). |
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. |
content[].grossPrice |
Decimal |
true |
Total amount of the order including VAT and shipping costs. |
content[].shippingCosts |
Decimal |
true |
Shipping costs including all fulfillment options. |
content[].lineItems |
Array[Object] |
true |
List of the line items of the order (order positions). |
content[].lineItems[].title |
String |
true |
Offer title |
content[].lineItems[].price |
Decimal |
true |
Unit price of an item incl. VAT. |
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). |
content[].lineItems[].priceRangeAmount |
Decimal |
true |
Amount by which the offer price was reduced within the price
range. |
content[].lineItems[].coSponsoringAmount |
Decimal |
true |
Amount by which the offer price was reduced by idealo according
to the cosponsoring agreement. |
content[].lineItems[].quantity |
Integer |
true |
Amount of items. |
content[].lineItems[].remainingQuantity |
Integer |
true |
Remaining amount of items, if the amount has been changed by a revocation. |
content[].lineItems[].sku |
String |
true |
This matches the value provided to idealo as a SKU in the export
from a shop |
content[].lineItems[].merchantId |
String |
true |
Unique identifier of marketplace participant, e.g. id of online
shop |
content[].lineItems[].merchantName |
String |
true |
Unique name of marketplace participant, e.g. name of online shop |
content[].lineItems[].merchantDeliveryText |
String |
true |
Delivery text set by the merchant |
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 |
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 |
content[].billingAddress.addressLine2 |
String |
true |
Additional address information |
content[].billingAddress.postalCode |
String |
true |
Postal code or zip code |
content[].billingAddress.city |
String |
true |
City |
content[].billingAddress.countryCode |
String |
true |
Country code (ISO 3166) |
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 |
content[].shippingAddress.addressLine2 |
String |
true |
Additional address information |
content[].shippingAddress.postalCode |
String |
true |
Postal code or zip code |
content[].shippingAddress.city |
String |
true |
City |
content[].shippingAddress.countryCode |
String |
true |
Country code (ISO 3166) |
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.costs |
Decimal |
true |
Shipping costs (without options costs) |
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 chosen fulfillment options. |
content[].fulfillment.options[].forwardOption |
String |
true |
Fulfillment options, possible values: PICKUP_SERVICE: "old appliance collection", available for orders with the fulfillment type FORWARDING and for orders for electronic equipment. TWO_MAN_DELIVERY: "two man delivery" service to the place of installation, only available for orders with fulfillment type FORWARDING. |
content[].fulfillment.options[].price |
Decimal |
true |
Fulfillment option costs. |
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) |
content[].refunds[].updated |
String |
true |
Date of the last update of the refund (ISO 8601, UTC
timezone) |
content[].voucher |
Object |
true |
Container for voucher information. |
content[].voucher.code |
String |
true |
Voucher code. |
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",
"processed" : "2021-01-01T00:00:00Z",
"updated" : "2021-01-01T00:00:00Z",
"status" : "PROCESSING",
"currency" : "EUR",
"offersPrice" : "171.50",
"grossPrice" : "202.00",
"shippingCosts" : "30.50",
"lineItems" : [ {
"title" : "Example product 1",
"price" : "150.50",
"priceRangeAmount" : "1.44",
"quantity" : 1,
"remainingQuantity" : 1,
"sku" : "product-sku-12345",
"merchantId" : "merchant_12345",
"merchantName" : "Example Electronics Ltd",
"merchantDeliveryText" : "Delivered within 3 working days"
}, {
"title" : "Example product 2",
"price" : "10.50",
"quantity" : 2,
"remainingQuantity" : 1,
"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",
"costs" : "10.00",
"tracking" : [ {
"code" : "xyz1234",
"carrier" : "Cargo"
} ],
"options" : [ {
"forwardOption" : "TWO_MAN_DELIVERY",
"price" : "20.50"
}, {
"forwardOption" : "PICKUP_SERVICE",
"price" : "0.00"
} ]
},
"refunds" : [ {
"refundId" : "example-refund-id",
"refundTransactionId" : "example-refund-transaction-id",
"status" : "OPEN",
"currency" : "EUR",
"refundAmount" : 1.99,
"created" : "2022-04-20T13:53:15.210648Z",
"updated" : "2022-04-20T13:53:15.210649Z"
} ],
"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 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 |
merchantOrderNumber |
String |
true |
Order number or id set by the merchant |
created |
String |
true |
Date when the order was created (ISO 8601, UTC timezone). |
processed |
String |
true |
Date when the order was paid (ISO 8601, UTC timezone). |
updated |
String |
true |
Date when the order status was updated (ISO 8601, UTC timezone). |
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. |
grossPrice |
Decimal |
true |
Total amount of the order including VAT and shipping costs. |
shippingCosts |
Decimal |
true |
Shipping costs including all fulfillment options. |
lineItems |
Array[Object] |
true |
List of the line items of the order (order positions). |
lineItems[].title |
String |
true |
Offer title |
lineItems[].price |
Decimal |
true |
Unit price of an item incl. VAT. |
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). |
lineItems[].priceRangeAmount |
Decimal |
true |
Amount by which the offer price was reduced within the price
range. |
lineItems[].coSponsoringAmount |
Decimal |
true |
Amount by which the offer price was reduced by idealo according
to the cosponsoring agreement. |
lineItems[].quantity |
Integer |
true |
Amount of items. |
lineItems[].remainingQuantity |
Integer |
true |
Remaining amount of items, if the amount has been changed by a revocation. |
lineItems[].sku |
String |
true |
This matches the value provided to idealo as a SKU in the export
from a shop |
lineItems[].merchantId |
String |
true |
Unique identifier of marketplace participant, e.g. id of online
shop |
lineItems[].merchantName |
String |
true |
Unique name of marketplace participant, e.g. name of online shop |
lineItems[].merchantDeliveryText |
String |
true |
Delivery text set by the merchant |
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 |
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 |
billingAddress.addressLine2 |
String |
true |
Additional address information |
billingAddress.postalCode |
String |
true |
Postal code or zip code |
billingAddress.city |
String |
true |
City |
billingAddress.countryCode |
String |
true |
Country code (ISO 3166) |
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 |
shippingAddress.addressLine2 |
String |
true |
Additional address information |
shippingAddress.postalCode |
String |
true |
Postal code or zip code |
shippingAddress.city |
String |
true |
City |
shippingAddress.countryCode |
String |
true |
Country code (ISO 3166) |
fulfillment |
Object |
true |
Container for fulfillment information. |
fulfillment.method |
String |
true |
Chosen fulfillment method. Must be one of [FORWARDING, LETTER, POSTAL, DOWNLOAD]. |
fulfillment.costs |
Decimal |
true |
Shipping costs (without options costs) |
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 chosen fulfillment options. |
fulfillment.options[].forwardOption |
String |
true |
Fulfillment options, possible values: PICKUP_SERVICE: "old appliance collection", available for orders with the fulfillment type FORWARDING and for orders for electronic equipment. TWO_MAN_DELIVERY: "two man delivery" service to the place of installation, only available for orders with fulfillment type FORWARDING. |
fulfillment.options[].price |
Decimal |
true |
Fulfillment option costs. |
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) |
refunds[].updated |
String |
true |
Date of the last update of the refund (ISO 8601, UTC
timezone) |
voucher |
Object |
true |
Container for voucher information. |
voucher.code |
String |
true |
Voucher code. |
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",
"processed" : "2021-01-01T00:00:00Z",
"updated" : "2021-01-01T00:00:00Z",
"status" : "PROCESSING",
"currency" : "EUR",
"offersPrice" : "171.50",
"grossPrice" : "202.00",
"shippingCosts" : "30.50",
"lineItems" : [ {
"title" : "Example product 1",
"price" : "150.50",
"priceRangeAmount" : "1.44",
"quantity" : 1,
"remainingQuantity" : 1,
"sku" : "product-sku-12345",
"merchantId" : "merchant_12345",
"merchantName" : "Example Electronics Ltd",
"merchantDeliveryText" : "Delivered within 3 working days"
}, {
"title" : "Example product 2",
"price" : "10.50",
"quantity" : 2,
"remainingQuantity" : 1,
"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",
"costs" : "10.00",
"tracking" : [ {
"code" : "xyz1234",
"carrier" : "Cargo"
} ],
"options" : [ {
"forwardOption" : "TWO_MAN_DELIVERY",
"price" : "20.50"
}, {
"forwardOption" : "PICKUP_SERVICE",
"price" : "0.00"
} ]
},
"refunds" : [ {
"refundId" : "example-refund-id",
"refundTransactionId" : "example-refund-transaction-id",
"status" : "OPEN",
"currency" : "EUR",
"refundAmount" : 1.99,
"created" : "2022-04-20T13:53:15.895441Z",
"updated" : "2022-04-20T13:53:15.895441Z"
} ],
"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. |
Request headers
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 |
[].merchantOrderNumber |
String |
true |
Order number or id set by the merchant |
[].created |
String |
true |
Date when the order was created (ISO 8601, UTC timezone). |
[].processed |
String |
true |
Date when the order was paid (ISO 8601, UTC timezone). |
[].updated |
String |
true |
Date when the order status was updated (ISO 8601, UTC timezone). |
[].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. |
[].grossPrice |
Decimal |
true |
Total amount of the order including VAT and shipping costs. |
[].shippingCosts |
Decimal |
true |
Shipping costs including all fulfillment options. |
[].lineItems |
Array[Object] |
true |
List of the line items of the order (order positions). |
[].lineItems[].title |
String |
true |
Offer title |
[].lineItems[].price |
Decimal |
true |
Unit price of an item incl. VAT. |
[].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). |
[].lineItems[].priceRangeAmount |
Decimal |
true |
Amount by which the offer price was reduced within the price
range. |
[].lineItems[].coSponsoringAmount |
Decimal |
true |
Amount by which the offer price was reduced by idealo according
to the cosponsoring agreement. |
[].lineItems[].quantity |
Integer |
true |
Amount of items. |
[].lineItems[].remainingQuantity |
Integer |
true |
Remaining amount of items, if the amount has been changed by a revocation. |
[].lineItems[].sku |
String |
true |
This matches the value provided to idealo as a SKU in the export
from a shop |
[].lineItems[].merchantId |
String |
true |
Unique identifier of marketplace participant, e.g. id of online
shop |
[].lineItems[].merchantName |
String |
true |
Unique name of marketplace participant, e.g. name of online shop |
[].lineItems[].merchantDeliveryText |
String |
true |
Delivery text set by the merchant |
[].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 |
[].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 |
[].billingAddress.addressLine2 |
String |
true |
Additional address information |
[].billingAddress.postalCode |
String |
true |
Postal code or zip code |
[].billingAddress.city |
String |
true |
City |
[].billingAddress.countryCode |
String |
true |
Country code (ISO 3166) |
[].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 |
[].shippingAddress.addressLine2 |
String |
true |
Additional address information |
[].shippingAddress.postalCode |
String |
true |
Postal code or zip code |
[].shippingAddress.city |
String |
true |
City |
[].shippingAddress.countryCode |
String |
true |
Country code (ISO 3166) |
[].fulfillment |
Object |
true |
Container for fulfillment information. |
[].fulfillment.method |
String |
true |
Chosen fulfillment method. Must be one of [FORWARDING, LETTER, POSTAL, DOWNLOAD]. |
[].fulfillment.costs |
Decimal |
true |
Shipping costs (without options costs) |
[].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 chosen fulfillment options. |
[].fulfillment.options[].forwardOption |
String |
true |
Fulfillment options, possible values: PICKUP_SERVICE: "old appliance collection", available for orders with the fulfillment type FORWARDING and for orders for electronic equipment. TWO_MAN_DELIVERY: "two man delivery" service to the place of installation, only available for orders with fulfillment type FORWARDING. |
[].fulfillment.options[].price |
Decimal |
true |
Fulfillment option costs. |
[].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) |
[].refunds[].updated |
String |
true |
Date of the last update of the refund (ISO 8601, UTC
timezone) |
[].voucher |
Object |
true |
Container for voucher information. |
[].voucher.code |
String |
true |
Voucher code. |
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",
"processed" : "2021-01-01T00:00:00Z",
"updated" : "2021-01-01T00:00:00Z",
"status" : "PROCESSING",
"currency" : "EUR",
"offersPrice" : "171.50",
"grossPrice" : "202.00",
"shippingCosts" : "30.50",
"lineItems" : [ {
"title" : "Example product 1",
"price" : "150.50",
"priceRangeAmount" : "1.44",
"quantity" : 1,
"remainingQuantity" : 1,
"sku" : "product-sku-12345",
"merchantId" : "merchant_12345",
"merchantName" : "Example Electronics Ltd",
"merchantDeliveryText" : "Delivered within 3 working days"
}, {
"title" : "Example product 2",
"price" : "10.50",
"quantity" : 2,
"remainingQuantity" : 1,
"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",
"costs" : "10.00",
"tracking" : [ {
"code" : "xyz1234",
"carrier" : "Cargo"
} ],
"options" : [ {
"forwardOption" : "TWO_MAN_DELIVERY",
"price" : "20.50"
}, {
"forwardOption" : "PICKUP_SERVICE",
"price" : "0.00"
} ]
},
"refunds" : [ {
"refundId" : "example-refund-id",
"refundTransactionId" : "example-refund-transaction-id",
"status" : "OPEN",
"currency" : "EUR",
"refundAmount" : 1.99,
"created" : "2022-04-20T13:53:14.956509Z",
"updated" : "2022-04-20T13:53:14.956509Z"
} ],
"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. |
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 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. |
Request fields
Path | Type | Optional | Description |
---|---|---|---|
carrier |
String |
true |
Shipping company Must have at least 1 and at most 31 characters. |
trackingCode |
Array[String] |
true |
Tracking code or tracking number 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". |
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. |
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. |
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". |
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
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. |
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. |
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". |
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. |
Request fields
Path | Type | Optional | Description |
---|---|---|---|
refundAmount |
Decimal |
false |
The amount you want to refund. Invalid refund amount format. |
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". |
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 60 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. |
Request headers
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) |
[].updated |
String |
true |
Date of the last update of the refund (ISO 8601, UTC
timezone) |
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" : "2022-04-20T13:54:13.360105Z",
"updated" : "2022-04-20T13:54:13.360106Z"
} ]