Any (webshop)

API

A flexible way to integrate serverside.

All communication with Clerk occurs through the API:

https://api.clerk.io/v2

Setting up this communication requires 4 steps, which are outlined in this guide. You need to:

  1. Sync data
  2. Retrieve results
  3. Visualize the results
  4. Add tracking

API Keys #

These keys are used to access the data of your Store. They are found in my.clerk.io > Settings > API Keys.

They consist of a Public key, which gives access to endpoints exposing non-sensitive data, and a Private Key which allows you to work with data on the Store and access sensitive data, such as customer and order information.

Private Keys can only be viewed once after being created for security reasons, and you can create as many as you need for different purposes.

1. Sync Data #

The first step is to get data in, allowing Clerk.io’s AI to understand your webshop and predict results. Clerk syncs each webshop domain as its own unique Store instance, which is accessed by a set of API Keys.

CRUD API #

You can sync your data using the CRUD API endpoints, which allow you to get, post, update, and delete resources on demand.

curl --request POST \
     --url 'https://api.clerk.io/v2/products' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "private_key": "osLqDAs5s2tlf3adpLv6Mp1hxx3f",
          "products":[
                {
                  "id": 123,
                  "name": "Green Lightsaber",
                  "description": "Antique rebel lightsaber.",
                  "price": 99995.95,
                  "brand": "Je’daii",
                  "categories": [987, 654],
                  "created_at": 1199145600
                },
                {
                  "id": 789,
                  "name": "Death Star Deluxe",
                  "description": "Death Star. Fool proof."
                  "price": 99999999999999.95,
                  "brand": "Imperial Inc.",
                  "categories": [345678],
                  "created_at": 11991864600
                }
             ]
           }'

The available objects are:

One of Clerk’s primary differentiators is that there’s no learning period, since we can utilize all existing orders from day one to understand current customer behavior.

Data Feeds #

In addition to using the CRUD API, it’s highly recommended to add a backup sync method. After all, many things can go wrong with API calls.

For example, your price server might crash, or a product attribute might contain an error that causes several calls to fail. To avoid these issues, consider using one or more Data Feeds as a daily backup for your CRUD calls.

Data feeds are one or multiple JSON files containing the webshops current catalogue.

Any data available in the feed when it is loaded will be what Clerk works with, except for orders, which are logged and do not need to be included in the feed after the first import.

Using the data feed is also a great way to preload Clerk with orders.

{
  "products": [ ... ],
  "categories": [ ... ],
  "orders": [ ... ],
  "customers": [ ... ],
  "pages": [ ... ],

  "config": {
    "created": 1567069830,
    "strict": false
  }
}

The data feed(s) should be available at a URL that can be accessed by the importer, which you configure in the my.clerk.io backend in System status > Data Sync. You can secure the feed, so only our importer can access it.

2. Retrieve Data #

Once data is synced, the AI analyzes it and builds intelligent indexes that can be retrieved through unique endpoints depending on the use-case.

E.g. to fetch the hottest products, you can use the recommendations/trending endpoint, and to display the top products for a search on “star wars,” you can use the search/predictive endpoint.

Endpoints #

All endpoints require you to send the public API key.

Endpoints that return results also require the " limit" argument to control the number of results to be returned.

Additional parameters depend on the endpoint you are calling. E.g. the best alternatives require products which is a list of product IDs to find accessories for, and any search-related calls need the query parameter to find matches.

You can find the necessary arguments for all endpoints in our API documentation.

By default, Clerk’s API returns all available results, but if necessary, Filters can be used to define a subset of matches.

Below is an example of making a call to a Search endpoint to find the top products for a search on “star wars,”

curl --request POST \
     --url 'https://api.clerk.io/v2/search/predictive' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "query": "star wars",
          "labels": ["Search - Predictive"]
        }'

Recommendations #

Below is an example of making a call to a Recommendations endpoint to find the hottest products.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "labels": ["Homepage - Trending"]
        }'

3. Visualize Results #

Clerk’s API always returns the IDs of the matches it found when returning results.

To visualize your data, you can make API calls serverside, retrieve the IDs of the matching products, and then fetch all the product-specific information from your webshop platform or PIM before rendering them.

Call

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 3,
          "labels": ["Homepage - Trending"]
        }'

Response

{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693
    ],
    "count": 3902,
    "facets": null
}

Clerk’s API can also be configured to send back any resource-specific information that you send to Clerk, such as prices, brand names, category URLs, blog cover images, and more.

With this, you often don’t need to make individual calls to your PIM before showing results, which will load your page faster.

Call

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 3,
          "labels": ["Homepage - Trending"],
          "attributes": ["id", "name", "price", "image", "url"]
        }'

Response

{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693
    ],
    "count": 3902,
    "facets": null,
    "product_data": [
        {
            "id": 12793,
            "image": "https://admin.awesomestore.com/image/14df",
            "name": "Baccarat Eye Small Oval Red Vase",
            "price": 520.0,
            "url": "https://admin.awesomestore.com/product/14df"
        },
        {
            "id": 13827,
            "image": "https://admin.awesomestore.com/image/51xs",
            "name": "Sabre Transat Garden Green 22cm Soup Spoon",
            "price": 13.96,
            "url": "https://admin.awesomestore.com/product/51xs"
        },
        {
            "id": 12693,
            "image": "https://admin.awesomestore.com/image/62x1",
            "name": "Sabre Transat Light Blue 22cm Dinner Fork",
            "price": 13.96,
            "url": "https://admin.awesomestore.com/product/62x1"
        }
    ]
}

4. Tracking #

Tracking must be added to keep Clerk’s AI up-to-date and personalize a visitor’s results during their session. It requires 4 steps:

  1. Generate a session ID for each visitor.
  2. Add descriptive labels to API calls returning results.
  3. Log a visitor’s clicks on products shown by Clerk.
  4. Log each order made on the webshop.

Create Visitor ID #

The session ID is also called the Visitor ID. It is required to log a user’s activity during a session on the webshop, including products they click, their searches, and categories they browse.

This activity is stored for each Store, and Clerk.io never shares it across Stores.

A visitor ID is just a string that is used to identify the session. It can be any alphanumerical characters, and we recommend keeping them to a maximum of 8 characters for the best performance.

For example, you could use PHP’s uniqid(), function to generate IDs that are unique for at least the current session. Once generated, this ID must be included in all calls to Clerk.io’s API for tracking to work.

<?php

session_start();

$current_visitor = uniqid(); //Example: "646f1f0584371"

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Add Labels #

Labels must be added to all calls that return results, such as search matches or alternatives on a product page. The labels argument is a list containing at least one string, which should be the descriptive label of this call.

We recommend using labels that describe the page where the call is used, and the type of results it shows. An example could be Homepage - Trending. This makes them easy to distinguish in analytics.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "labels": ["Homepage - Trending"],
          "visitor": $_SESSION["clerk_visitor_id"]
        }'

Log Clicks #

You should log each click on a Clerk.io product with the log/click endpoint.

It’s important to only make this call when the product clicked is actually shown by Clerk.io and not the webshop platform itself. Otherwise, it will look as if all products are found through Clerk.

The call should also contain the api which is the endpoint used to show the product that was clicked, and product which contains the ID of the product that was clicked.

Search & Recommendations #

Logging clicks are done by adding the parameters to the call based on the endpoint used to show the product that was clicked. This is straightforward as it uses data from the setup you have made yourself.

curl --request POST \
     --url 'https://api.clerk.io/v2/log/click' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "labels": ["Homepage - Trending"],
          "api": "recommendations/trending",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793
        }'

Email Recommendations #

Logging clicks works differently, as you will receive the data from GET requests that are forwarded by Clerk.io. You should monitor if the URL includes parameters indicating that visitors land on a product page from an Email Recommendation.

These requests will always contain the following query parameters:

{
  "utm_source": "clerk",
  "utm_medium": "email",
  "utm_campaign": "Welcome Email - Bestsellers",
  "utm_content": "clerk-recommendations",
  "clerk_product": 12793,
  "clerk_labels": "Welcome Email - Bestsellers",
  "clerk_api": "recommendations/popular",
  "clerk_n": 0,
  "clerk_external": 1
}

We recommend monitoring if the URL includes clerk_external: 1 and if it does, log the click with the data you receive.

clerk_api contains the API endpoint with a * character to avoid encoding issues. This should be changed to / when logging the click. external: 1 should be added to the call so Clerk knows the click comes from an email.

Here’s an example log/click call that uses the above data:

curl --request POST \
     --url 'https://api.clerk.io/v2/log/click' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "labels": ["Welcome Email - Bestsellers"],
          "api": "recommendations/popular",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793,
          "external": 1
        }'

Log Products #

When visitors view product pages, this should be logged so it can be used to personalize results - specifically the visitor-related ones like Visitor Recommendations or Visitor Alternatives.

If you use any endpoints that already need the product ID to work, like recommendations/substituting or recommendations/complementary, Clerk.io will log the product ID automatically.

However, if you are not using these, you need to make a separate call to log/product, with the ID of the product being browsed.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793
        }'

Log Sales #

Clerk.io’s AI relies heavily on orders to predict results, so tracking these in real time is key. The log/sale endpoint is used for this.

With the visitor ID included in this call, Clerk will understand which products were shown, clicked on, and finally purchased. This allows the AI to always stay up-to-date and change results on the fly based on customer behavior.

This call also associates the Visitor ID with the email address or customer ID of the purchaser, allowing for even better personalization through customer-specific recommendations.

The id of products should match the IDs that are logged for clicks. E.g. for configurable products you should track the parents ID in both log/click and log/sale regardless of the variant bought.
price is the unit price. It will be multiplied by quantity in Analytics.
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0",
          "sale": 567,
          "products": [
            {
              "id": 12793,
              "price": 99.95,
              "quantity": 2
            },
            {
              "id": 1546,
              "price": 14.00,
              "quantity": 2
            }
          ],
          "customer": 1234,
          "email": "theone@matrix.com",
          "visitor": $_SESSION["clerk_visitor_id"]}' \
       https://api.clerk.io/v2/log/sale