Bol.com to Zendesk: connect and set up

What the connector does and does not do

Schakel checks Bol.com regularly and puts what needs your attention into Zendesk as a ticket: unhandled returns and cancellation requests from customers. If you also want a customer’s order history in Zendesk, you can have every new order created as a solved ticket (off by default). For each ticket Schakel adds the customer as a user in Zendesk, the order data in ticket fields and an overview with products, EAN, quantities and amounts in the first comment. When a return or request has been handled on Bol.com, an internal note is added to the ticket. What it cannot do: Bol.com does not release customer questions and messages through its API, so they do not arrive in Zendesk on their own (see the last step for the workaround). A reply to a buyer cannot be sent from Zendesk either: you reply in the Bol.com Partner Platform, and the first comment of every ticket contains a direct link there. Schakel never writes anything back to Bol.com and never sends anything to a buyer.

What you need

Three things. A Zendesk account with API access: every Zendesk Support or Suite plan works, the trial included. On the entry plans the API limit is low (around 10 requests a minute), so the first run may take place in parts. Someone with the Admin role in Zendesk, because only an admin sees the Admin Center and can create an OAuth client. And the API details of your Bol.com account: a Client ID and a Client Secret for the Retailer API, which you create yourself in the Bol.com Partner Platform (the next step). You do not need a Zendesk password or API token: you create an OAuth client in your own Zendesk and give Schakel only its client ID and secret.

Create your Bol.com API credentials

Log in to the Bol.com Partner Platform, click your name in the top right and go to Instellingen (Settings). Scroll to Diensten (Services), open API Instellingen (API Settings) and under Client credentials voor de Retailer API click + Aanmaken (Create). Give the key a recognisable name, for example Schakel Zendesk, save, and copy the Client ID and (via Toon secret) the Client Secret. Every screen is shown with a screenshot in the Bol.com guide. Schakel only uses the key to read.

Or go straight to https://partner.bol.com/sdd/preferences/services/api

Connect Bol.com in Schakel

In Schakel, go to Connections (or click Go to connections in the first step of the setup). Click Connect an account under Bol.com, name the account, paste the Client ID and the Client Secret and click Connect and test. Schakel tests the details at once; a wrong connection is not saved. If you already connected Bol.com for another connector, simply pick that account again.

Create your own OAuth client in Zendesk (1/4): open the overview

Schakel connects with an OAuth client that you create yourself in your Zendesk. It takes a few minutes and you stay in control: you create it, you can replace or delete it. Log in to Zendesk as an admin and open the Admin Center (Beheercentrum). In the menu go to Apps and integrations (Apps en integraties), APIs (API’s) and choose OAuth clients (OAuth-clients). Do not choose Global OAuth clients (Externe OAuth-clients): those are for apps that Zendesk itself has approved. Click Add OAuth client (OAuth-client toevoegen) at the top right. Zendesk shows the Admin Center in the language of your account; the screenshots in this guide are Dutch, and the English names are given alongside.

Create your own OAuth client in Zendesk (2/4): name and identifier

Fill in the Add OAuth client form from top to bottom. Naam (Name): Schakel. Zendesk shows this name in the list of third-party apps. Beschrijving (Description): one sentence, for example Connects Bol.com returns and cancellation requests to Zendesk tickets through Schakel. Bedrijf (Company): the name of your own company; Zendesk fills in a name already. Logo: skip it. Identifier: a short, unique name without spaces, for example schakel (the screenshot shows schakel_docs_demo). This is the client ID you enter in Schakel in a moment. It is not secret, but it must be unique within your Zendesk.

Create your own OAuth client in Zendesk (3/4): confidential, address and scopes

Type client (Client type): choose Vertrouwelijk (Confidential). A confidential client gets a secret, and with it Schakel requests its own access token from Zendesk. An Openbaar client (Public) has no secret and does not work here. Omleidingswebadressen (Redirect URLs): enter https://app.schakel.app/api/connections/zendesk/callback. Schakel does not use this address for this connection, but enter it as shown here. Toegestane bereiken (Allowed scopes): choose read and write, or leave the field empty (Zendesk then allows all scopes). Schakel asks for nothing more, and only uses it to create tickets and users and to read the groups (see the next steps).

Create your own OAuth client in Zendesk (4/4): save and copy the secret

Click Opslaan (Save) at the bottom. Zendesk then opens the OAuth-client bewerken (Edit OAuth client) screen. At the bottom, under Geheim (Secret), your client’s secret now appears with a Kopiëren (Copy) button; before saving it only says you have to save first. Copy the secret at once and keep it in your password manager: Zendesk shows it in full only once. The secret gives access to your Zendesk, so do not send it by email or chat. Your client ID is the identifier from the previous step; you also see it in the list of OAuth clients.

Connect Zendesk in Schakel

Go to step 2 of the setup (Connect Zendesk), or to Connections. Fill in three fields. Zendesk subdomain: the part before .zendesk.com in the address of your Zendesk. If that is mycompany.zendesk.com, your subdomain is mycompany; if your helpdesk has its own domain, still use the .zendesk.com address. Client ID (unique identifier): the identifier from step 2, for example schakel. Client secret: the secret you just copied. Click Connect Zendesk. Schakel then requests its own access token from Zendesk and tests it with one read request; a wrong combination is not saved. The secret is stored encrypted and never shown again. What Schakel does with it: create and update tickets and users, create five ticket fields for the Bol.com data (Bol order ID, Bol return ID, Bol RMA, Bol fulfilment and Bol channel) and read the list of groups. Schakel deletes nothing, only looks at its own tickets and calls nothing else.

Choose what becomes a ticket

Step 3 of the setup. Returns (recommended, on): one ticket per unhandled return, with the customer, the products, the return reason and a link to the Partner Platform. Cancellation requests (recommended, on): one ticket per order with an open request from the customer. Schakel cancels nothing itself; you decide in the Partner Platform. Every new order (off by default): a ticket per order, only useful if you want to see a customer’s order history in Zendesk. In a busy shop this creates many tickets, so leave it off unless you really want it. Follow-up notes (recommended, on): an internal note and a tag on the existing ticket as soon as Bol.com has handled the return or request. The ticket is not closed automatically. Click Save and continue: until you do, the step does not count as done.

Set the details

Step 4 of the setup. Only from this date: leave empty to start from now, or pick a date if you also want older returns; anything before it gets no ticket. Bol.com keeps data only briefly and only returns about three months of orders itself, so going back further rarely helps. Extra tags: optional, separated by spaces. Every ticket gets these tags on top of bol and the kind of ticket. Assign to group: the Zendesk group new tickets go to; without a group your Zendesk rules decide. If the groups cannot be loaded, just continue without a group and change it later. Status of order tickets: only matters if you turn on orders as tickets. Solved keeps your inbox empty and is the recommendation. Click Save and continue.

Review the dry run and start

Step 5 of the setup. Click Show the dry run. Schakel then reads Bol.com and shows how many returns, cancellation requests and, if enabled, orders would become a ticket. Nothing is created in Zendesk. If it says at least that many, Bol.com has more to read than fits in one go and the rest follows in the next runs. If the number looks right, click Start: the first sync runs at once and afterwards Schakel keeps Zendesk up to date on its own. If the number is surprisingly high, check the start date first.

What a ticket looks like in Zendesk

Each ticket has the kind and the number as its subject, for example Bol retour 3100001: product name or Bol annuleringsverzoek order A000.... The first comment is an internal note (the buyer does not see it) with the link to the Partner Platform, the details, the items with product name, SKU, EAN (as a link to bol.com), quantity and amount, the order date and order status (open, shipped or cancelled), whether logistics run via bol (FBB) or you ship yourself (FBR), for a return also the reason and the customer’s remark, and the customer details. The SKU and order status only appear while bol still shows the order. The fields Bol order ID, Bol return ID, Bol RMA, Bol fulfilment and Bol channel are filled, so you can search and filter on them. Tags: bol plus bol_return, bol_cancellation or bol_order, plus your own tags. When a return has been handled, an internal note and the tag bol_return_handled are added; when a cancellation request disappears, bol_cancellation_resolved. With these you can build a view in Zendesk of what is still open. The customer is a user in Zendesk, so all tickets from the same buyer sit together.

Read the dashboard

After the first run the connector is on your dashboard. At the top you see the number of tickets opened, split into returns, cancellation requests and, if enabled, orders, and the number of failed tickets. Below are the latest ten tickets with the Bol.com number, the type, the ticket number in Zendesk and the status: Open, Solved or Failed. If you do not want to wait, click Sync now. Schakel retries a failed ticket for about three days; the connector log names the reason. If access to Zendesk has expired or been revoked, a notice at the top links to Connections.

Change your choices later

All choices from the setup are also under Settings in the connector menu. A change applies from the next run. On the Connections page you see your Bol.com and Zendesk accounts; that is also where you reconnect or remove a connection.

Replace the secret

Do you want to replace the secret, for example because it leaked or because a colleague with access leaves? In Zendesk (Admin Center, Apps and integrations, APIs, OAuth clients) open your client to edit it and generate a new secret at the bottom under Geheim (Secret). Copy it at once. Then in Schakel go to Connections, paste the new secret at your Zendesk account and click Save and test. The old secret then stops working; as long as Schakel does not have the new secret yet, Schakel says access has expired. Your settings are kept and Schakel creates the tickets missed in the meantime afterwards.

Revoke access

To take access away from Schakel entirely, delete the OAuth client in Zendesk (Admin Center, Apps and integrations, APIs, OAuth clients, your client). Only an admin can do that and it cannot be undone. Without that client Zendesk no longer gives Schakel access tokens, so Schakel can no longer do anything in your Zendesk; existing tickets stay. Then also remove the Zendesk connection on the Connections page in Schakel: Schakel then wipes the stored secret on its side. Removing it in Schakel alone is not enough if you want to be sure the secret works nowhere: that is done in Zendesk. If you want to connect again later, create a new OAuth client and enter its details in Schakel.

Optional: forward customer questions

Customer questions only live in the Partner Platform and in the notification mails from Bol.com; the API does not release them. The workaround: forward those notification mails to your Zendesk support address, and every mail becomes a ticket. You find your support address in Zendesk under Admin Center, Channels, Email; by default it is support@mycompany.zendesk.com. In your mail program set up a filter on mails from Bol.com about a new customer question and have it forward them to that address (in Gmail you must verify the forwarding address first). These are plain email tickets, not linked to Schakel. Replies cannot reach the buyer through Zendesk here either: answer the question in the Partner Platform and use the ticket as a worklist.