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 register the employee at Coolblue by creating an account. This returns a customerId that you use in subsequent calls (for example generating a one-time login link and checking draft orders). The exact request and response contracts are documented in the Cafetariaplan API Swagger UI.

ACCESS_TOKEN="eyJhbGciOi..."

curl -X POST \
  "https://<acceptance-host>/cafetariaplan-api/accounts" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "User-Agent: Coolblue-YourCompanyName" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "employee@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "isoLanguageCode": "nl",
    "companyId": "00000000-0000-0000-0000-000000000000"
  }'

Next, call POST /login with the returned customerId to obtain a one-time login URL for redirecting the employee to Coolblue.

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.

Next steps

Continue with one of these references: