Business API – Getting started | Coolblue Business Journeys

Prerequisites

An active business agreement with Coolblue and access to the Business Journeys team.
A technical contact person responsible for the integration.
Network access to call HTTPS endpoints from your systems.
Valid API credentials (client_id and client_secret) for the Business API. You can request these via your Coolblue contact.

Credentials are shared securely using email and mobile phone number with two‑factor authentication. For more details, see Authentication.

Environments

The Business API is available in two environments: Acceptance for testing and Production for live traffic. Orders created in Acceptance are not processed by Coolblue and no transactional communication (emails or SMS) is sent.

Environment	Base URL	Purpose	Order processing	Emails / SMS
Acceptance	`https://<acceptance-host>/business-api`	Test your integration end‑to‑end without affecting real customers.	No – orders are not fulfilled.	No – transactional emails/SMS are disabled.
Production	`https://<production-host>/business-api`	Serve real customers with live data and real orders.	Yes – orders follow the normal Coolblue fulfilment flow.	Yes – customers receive standard Coolblue communication.

Always start in the Acceptance environment and only move to Production once you have completed your tests. See Environments for more details across all Business Journeys APIs.

Authentication

The Business API uses OAuth 2.0 with client credentials for authentication. You obtain an access token using your client_id and client_secret, then include that token in the Authorization header of each API request.

1. Obtain an access token

curl -X POST \
  "https://<acceptance-host>/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

A successful response returns a JSON payload similar to:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Store the access_token securely and reuse it until it expires. When it expires, request a new token using the same flow.

For a general overview of authentication across all Business Journeys APIs, see Authentication.

Your first request

Once you have an access token, you can call the Business API. The example below shows a simple request to create an order (replace placeholder values with your own).

Example: create an order

ACCESS_TOKEN="eyJhbGciOi..."

curl -X POST \
  "https://<acceptance-host>/business-api/orders" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "id": "YOUR_CUSTOMER_ID",
      "email": "customer@example.com"
    },
    "items": [
      {
        "sku": "PRODUCT_SKU",
        "quantity": 1
      }
    ]
  }'

For the full list of fields, validation rules and response formats, refer to the Business API reference in Swagger UI

Error handling

The Business API uses standard HTTP status codes:

2xx – request succeeded.
4xx – client error (invalid request, missing fields, invalid token).
5xx – server error (temporary issues on Coolblue's side).

Error responses include a machine‑readable error code and a human‑readable message. Log both the HTTP status code and the error body for troubleshooting.

Common pitfalls

Calling the wrong environment (Acceptance vs Production) when testing or going live.
Using expired access tokens instead of requesting a new one.
Missing or invalid mandatory fields in order requests.
Not logging request IDs / correlation IDs, making it harder to investigate issues.

If you encounter an issue, first check the FAQ & Troubleshooting page.

Support

If you need help integrating with the Business API, contact the Business Journeys team at dev-business@coolblue.nl.

To help us resolve your issue quickly, please include:

Environment (Acceptance or Production).
API (Business API).
Timestamp and timezone of the failing request.
HTTP method and URL you called.
HTTP status code and error response (if any).
Any relevant request IDs or correlation IDs from your logs.

See Support for more details.

Deep‑dive: Business API integration guide

For a full description of the Business API concepts and integration flows (initial product upload, product updates, product images, order creation, etc.), see the detailed Business API integration guide.