Cafetariaplan API – Getting started | Coolblue Business Journeys

Prerequisites

An agreement with Coolblue to offer products via cafetariaplan.
One or more cafetariaplan configured on your side (employers, employees, budgets).
Valid API credentials (client_id and client_secret) for the cafetariaplan API.

For how to request credentials and how we share secrets, see Authentication.

Environments

The cafetariaplan API is available in the same Acceptance and Production environments as the other Business Journeys APIs. Orders in Acceptance are not processed and no transactional communication is sent.

Environment	Base URL	Purpose
Acceptance	`https://<acceptance-host>/cafetariaplan-api`	Test your integration end‑to‑end with test employers and employees.
Production	`https://<production-host>/cafetariaplan-api`	Serve real employers and employees with real orders.

See Environments for more information.

Authentication

Authentication works the same way as for the Business API: OAuth 2.0 with client credentials. Obtain an access token using your client_id and client_secret, then use it in the Authorization header.

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"

See Authentication for details.

Your first request

A typical first step is to create or reserve a cafetariaplan order for an employee. The exact request shape is documented in the cafetariaplan API Swagger UI

ACCESS_TOKEN="eyJhbGciOi..."

curl -X POST \
  "https://<acceptance-host>/cafetariaplan-api/orders" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "employerId": "EMPLOYER_ID",
    "employeeId": "EMPLOYEE_ID",
    "items": [
      {
        "sku": "PRODUCT_SKU",
        "quantity": 1
      }
    ],
    "budgetYear": 2026
  }'

Common pitfalls

Using production employee identifiers in Acceptance (or vice versa).
Sending requests without a valid plan/budget configured on your side.
Calling the wrong environment when validating end‑to‑end flows.

Check the FAQ for cafetariaplan‑specific questions.

Support

For help with the cafetariaplan API, contact dev-business@coolblue.nl and mention that your question is about “cafetariaplan API”.

See Support for what information to include.

Deep‑dive: Cafetariaplan integration guide

For a full description of the Cafetariaplan concepts and integration flows (onboarding, login, website, orders and communication), see the detailed Cafetariaplan API integration guide.