Handling Click-Tracking in API Setups Directly with the API

Check the steps you need to follow add click-tracking on API setups.

Clerk.io uses click-tracking both to personalise results for visitors and to show the performance in my.clerk.io.

Follow these steps to set up click-tracking

1. Assign Visitor ID’s

The first step is to give each visitor a unique ID. The simplest way to do this is by saving a unique, random, 16 letter string in a cookie. Only alpha-numeric strings up to 32 characters are allowed.

A visitor ID should only be unique to the device. Cross-device association is handled automatically by Clerk.io if we detect that a customer ID / email address is used with multiple visitor IDs.

Every time you make an API request you must send the visitor ID from the cookie as the visitor parameter.


visitor: "7t2i2H8l"

2. Include Labels in API Calls

Since the Clerk.io dashboard allows you see the performance of each individual part of Search and Recommendations, you should always include the labels parameter in each call where you show results.

“labels” is a list containing at least 1 string, which is the name that will be shown when checking performance in my.clerk.io.

Full example call with visitor ID and labels:

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "STyoUzAmh3JeZvw2LTOyo6CsUOPBtri5",
          "visitor": "7t2i2H8l",
          "limit": 30,
          "labels": ["VisitorRecommendations"]}' \

3. Add Click-Tracking

The click-tracking should be added to all products returned from Clerk.io .

Click-tracking is handled through the log/click API endpoint .

The call should be made when the visitor clicks a product returned from Clerk.io and must include the visitor parameter and the ID of the product being clicked.


curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "STyoUzAmh3JeZvw2LTOyo6CsUOPBtri5",
          "visitor": "7t2i2H8l",
          "product": 123}' \

4. Add Sales-Tracking

Finally, if you have not already set it up, you need to track the sales coming from the webshop.

Sales-tracking can also be done either through Clerk.js or via API call.

Sales-tracking is handled through the log/sale API endpoint.

The call should be made from the Order Success page, and must include the visitor ID as well as all the information for the sale:

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "STyoUzAmh3JeZvw2LTOyo6CsUOPBtri5",
          "sale": 567,
          "products": [
              "id": 1,
              "price": 99.95,
              "quantity": 2
              "id": 33,
              "price": 14.00,
              "quantity": 2
          "email": "theone@matrix.com",
          "visitor":  "7t2i2H8l"}' \

There! Now you have click-tracking running in your API setup.