Coolblue Business API

Overview

Features

This section highlights some particularities of the various Business API capabilities.

Products

A product is anything that can be sold by Coolblue. These can be physical products, but also product combinations, services and other "product types". Each product is assigned a unique product ID, also known as an SKU.

Initial Product Upload

The Business API supports retrieving product information for a single product. If required, it is possible to manually upload the product information for the initial set of products in the selected assortment. Such bulk upload is facilitated via a different mechanism.

Product Updates

When maintaining a copy of the product information in your system, it is important that you keep the snapshots of the data up-to-date. Product catalog of Coolblue is constantly evolving, and any part of the product information can change. Some highly volatile properties, like prices and stock availability, could change multiple times throughout the day. Other product details usually change less often.

Note: product information returned by the Business API might be outdated compared to the information available on the Coolblue website. Because of caching, it can take up to 1 hour for any product information changes to be visible in the Business API.

It is possible to receive product updates whenever a product is changed. For that you need to register a webhook, and Coolblue will push notifications to it whenever a product is updated (with a delay of up to 1 hour). The notifications include a product ID that can be used to retrieve the latest product information from the Business API.

On one hand staying up-to-date is important, on the other hand you should not want to query data for the full assortment on a regular basis to avoid over-querying.

Some product properties do not trigger product update notifications, for example changes to available product services.

Product Images

Product images are hosted on the Coolblue CDN available at https://image.coolblue.nl/transparent/max/{image size}/products/{image ID}

where the {image ID} is the imageIdincluded in the product information returned by the Business API, and the {image size} represents the height and width of the image. Only a predefined set of image sizes is supported: supported image sizes.

Orders

The Business API supports placing orders on behalf of customers. Orders are invoiced to a business customer provided in the request.

Time Slots

Large products delivered by Coolblue (like washing machines and TVs) require to select a “time slot”, a specific delivery date and time. Time slots depend on the properties of a product (size, weight, product type) and address (capacity on routes, delivery constraints).

When requesting timeslots, response includes an entry per available day. Then, a second request has to be made to get all the available time slots for the selected day. This last step claims teh time slot for 15 minutes. If an order is not placed within that time, then time slot has to be requested again.

All dates and times are returned in the UTC time zone.

Note: delivery logic of Coolblue needs to know whether a significant "hurdle" needs to be passed, necessitating 2-man delivery.

Deliveries to the ground floor with only a low door frame can be handled with a 1-man delivery. Deliveries to higher floors without an elevator (i.e. flights of stairs) or over a significant (> 10 cm) doorstep the "requiresLifting" flag has to be set to “true”.

Assuming this is always false will result in failed deliveries, as our delivery staff might not be able to single-handedly deliver the product. Assuming it is always false results in significantly higher delivery costs for Coolblue. Therefore we require users of this API to include this check when requesting time slots, to accurately select the delivery routes.

In order to place an order with a specific time slot, include the chosen time slot ID in the “Create Order” request.