Table of Contents
2.2.1. Login via Coolblue Cafetariaplan API
4.3.1 Transaction communication
Example: Fully automated integration
Coolblue Business Cafetariaplans
Customizable cafetariaplan solutions for our business partners to create tailored customer journeys.
Over time Coolblue will expand the cafetariaplan capabilities and customizations to introduce new and expand existing features. We make all reasonable efforts to maintain backwards compatibility. In an unlikely event when a breaking change is required, we ensure to inform our partners at least two weeks in advance.
The capabilities described in this document are building blocks that allow our partners to integrate various parts of the cafetariaplan customer journey with Coolblue. Not all steps and features are necessary or feasible for every integration. We advise to integrate in incremental steps, starting with essential steps and adding more features as needed.
Feedback is always welcome: please share your questions, comments and concerns with your Coolblue Specialized Sales consultant.
Glossary
This document uses the following terminology:
- Cafetariaplan is a type of employee benefit that allows employees to convert part of their gross salary into other less taxed benefits like purchasing electronics.
- Employee (also known as End customer or User of cafetariaplan) is the person who receives cafetariaplan benefits. It is the person who receives products ordered from Coolblue.
- Employer (also known as Business customer or Company) is the employer of the employee defined above. It is the company that is invoiced for the cafetariaplan orders.
- Cafetariaplan provider is the company that provides employees access to their cafetariaplan benefits. It is the company that integrates with Coolblue to create customized cafetariaplan customer journeys.
- Coolblue website is the main entry point for employees to access their cafetariaplan assortment at Coolblue. For example www.coolblue.be in Belgium.
- Closed Community is a closed environment on the Coolblue website that provides employees access to the company landing page and a limited cafetariaplan assortment. Usually each employer will have their own customized closed community.
-
Overview
2. Onboarding at Coolblue
2.1. Employer Onboarding
In order to configure a cafetariaplan for a new employer, their company has to be manually registered in Coolblue systems. The registration process involves several parts:
- Create a new business customer in the Coolblue system.
- Create a new cafetariaplan closed community.
- Create a new closed community landing page on the Coolblue website.
After this initial registration, Coolblue sends the following information to the cafetariaplan provider:
- Landing page URL. It has to be used when redirecting employees to the Coolblue website.
- Unique company ID for the employer. It has to be used when calling Coolblue APIs (for example when creating an order).
Note: It is also possible to set up a single closed community for all employers of the same cafetariaplan provider. This setup provides the same assortment and single landing page for every employer.
2.2. Employee Onboarding
In order for the employee to access the Coolblue website, they need to be logged in.
Note: Regardless of the onboarding approach, employees are not able to see draft orders or any previously created orders in their Coolblue account. It is the responsibility of the cafetariaplan provider to display pending or placed orders to the employees if this feature is needed.
2.2.1. Login via Coolblue Cafetariaplan API
This integration requires the cafetariaplan provider to register the employee at Coolblue before they are redirected to the Coolblue website.
The login process is done in two steps:
- The cafetariaplan provider calls the Cafeteriaplan API to create a new account for the employee. The required data includes first name, last name, email address and preferred language. In response, the API returns a Coolblue customer ID for the newly registered employee. Refer to the contracts section at the end of this document.
- The cafetariaplan provider calls the Cafeteriaplan API to generate a short-lived one-time login link. The link allows the cafetariaplan provider to redirect the employee to the Coolblue website and automatically log them into their Coolblue account. In this flow the employee does not need to enter their password on the Coolblue website.
After receiving the token and parameters, the client can also add a parameter for the return URL. This parameter will be used for the Call to Action button on Coolblue’s Thank You page. The parameter is called returnurl. Keep in mind that this parameter should be a valid URL.
3. Coolblue Website
In order to see the assortment available at Coolblue, employees have to visit the Coolblue website. Coolblue does not provide separate websites for cafetariaplan integrations. Instead, the main website is customized for employees linked to a cafetariaplan.
The cafetariaplan provider is responsible for redirecting employees to the Coolblue website using the URL provided by Coolblue.
Please note that the Coolblue website differs per country:
- Belgium: www.coolblue.be
- The Netherlands: www.coolblue.nl
- Germany: www.coolblue.de
Note: It is not possible for employees to order products from the assortment of the website in another country.
3.1. Closed Community Portal
A closed community portal is a closed environment on the Coolblue website that has a custom landing page, limited assortment and extra features available only for cafetariaplan employees.
The landing page of the closed community has to be configured as part of onboarding the employer based on the limited assortment of the cafetariaplan. It contains links to different product categories available in the assortment. This page is only visible to customers that are part of the cafetariaplan, and is thus not visible to regular customers of Coolblue.
Note: It is not possible to show employees only specific product types (e.g. only phones or laptops) based on what they select on the cafetariaplan provider platform. Coolblue creates a single closed community per employer, and its assortment includes all product types eligible for the cafetariaplan. It is the responsibility of the cafetariaplan provider to validate that the type of the selected product is correct. To facilitate the validation, Coolblue provides an API for retrieving product information that includes the product types.
4. Orders
The ordering process via cafetariaplans is performed in multiple steps.
4.1. Create draft order
First, the employee selects desired products and provides customer details required to create a draft order at Coolblue. Draft orders include a snapshot of the shopping cart (products and prices), contact details, delivery details, company ID and any other relevant information necessary for placing actual orders later.
A draft order has an expiry period, which is managed by Coolblue, and by default is 24 hours. Draft order price is preserved in this time frame.
The cafetariaplan provider can retrieve the draft order details from the Cafetariaplan API and use this information to approve or reject the order. Once the order is approved, the cafetariaplan provider needs to call the Cafetariaplan API to convert the draft order.
4.2. Convert draft order
As soon as the draft order is validated and accepted on the cafetariaplan provider system, it can be converted into an actual order at Coolblue by calling the Cafetariaplan API. This action has to be taken within the expiry period of the draft order.
4.3. Post-order processing
After an order is created at Coolblue, the cafetariaplan provider can request the status of the order. As soon as this status changes to indicate that the order has been shipped, the employee should receive the order within a single day. This information can be used to determine at what date the cafetariaplan benefit should start for the employee.
4.3.1 Transaction communication
There are several types of transactional communication sent to Coolblue customers:
- Order confirmation is sent after an order has been placed.
- Shipment confirmation is sent after the order is processed and handed over for delivery.
- Delivery updates are communicated via email and SMS.
- Invoice communication.
For cafetariaplan orders the communication is split: the employee receives the communication about the order and delivery, whereas the employer receives the invoicing information. Some types of emails can be disabled completely depending on the needs of the integration.
Example: Fully automated integration
An example of a feature-reach fully automated customer journey with a custom Coolblue implementation tailed for the cafetariaplan provider:
- Coolblue configures a closed community for each employer company with a custom website landing page in all supported languages.
- The cafetariaplan provider configures language-specific redirect links for each employer company based on the created closed communities.
- The cafetariaplan provider creates an account for each employee by integrating with the Coolblue Cafetariaplan API.
- The cafetariaplan provider redirects an employee to a custom landing page on the Coolblue website.
- The employee searches for a desired product from the limited assortment of their closed community. It is not possible to select products outside the assortment.
- The employee enters their contact and delivery details during the checkout flow on the Coolblue website.
- At the end of the checkout, Coolblue stores the information as a draft order, and redirects the employee to the cafetariaplan provider platform.
- Users will be redirected to the provided returnurl.
- The cafetariaplan provider retrieves pending draft orders for a given employee from the Coolblue Cafetariaplan API.
- Response will include a list of pending orders with products and their product type IDs. Keep in mind that one draft order can hold multiple products of different product types.
- The cafetariaplan provider validates the automatically registered order on the cafetariaplan provider platform to ensure it fits into their budget.
- The cafetariaplan provider converts the draft order using the Coolblue Cafetariaplan API.
- Coolblue processes the order and ships it to the employee.
- The cafetariaplan provider retrieves the status of the order from Coolblue Business API and displays it to the employee.