Overview

All communication with Clerk.io’s AI happens through our super-fast REST API.

Regardless of the webshop platform, Clerk can always be integrated via API or with our Clerk.js solution that makes API calls from the frontend.

We then build extensions and integrations that bundle features from the API and Clerk.js to make integration smooth for any platform.

API #

This is the cornerstone of Clerk.io’s functionality. It is accessible at this URL:

https://api.clerk.io/v2

You communicate with the API using API keys and a range of different endpoints that return data in JSON format.

Call

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

Response

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

Setting up this communication requires you to sync data, retrieve results, visualize these results, and add tracking. All the details are outlined in the API guide.

Clerk.js #

This JavaScript library makes it easy to integrate Clerk.io’s services into any frontend.

Clerk.js does all the heavy lifting, such as making network requests, gracefully handling errors, rendering into the DOM, and applying tracking out of the box.

<!--Clerk.js script-->
<script type="text/javascript">
  (function(w,d){
    var e=d.createElement('script');e.type='text/javascript';e.async=true;
    e.src='https://cdn.clerk.io/clerk.js';
    var s=d.getElementsByTagName('script')[0];s.parentNode.insertBefore(e,s);
    w.__clerk_q=w.__clerk_q||[];w.Clerk=w.Clerk||function(){ w.__clerk_q.push(arguments) };
  })(window,document);

  Clerk('config', {
    key: 'insert_api_key'
  });
</script>

<!--Recommendations snippet-->
<span class="clerk" data-template="@bestsellers"></span>

Setting up Clerk.js requires you to insert the tracking scripts, create designs, and add snippets to your frontend. All the details are outlined in the Getting Started guide.

Extensions #

These are installed into the platform as packages that bundle data feeds, API calls, and Clerk.js. They handle syncing, tracking, and inserting snippets. Examples include:

• Magento2
• WooCommerce
• Prestashop

As the extension will be installed on your server, you can extend or change it in the code as you see fit. Just make sure to keep your changes separate from the core files to avoid overwriting them when you update to a new release.

Most extensions sync data by creating endpoints on the webshop, which are then accessed with the Public and Private Keys.

When you run a data sync, Clerk’s importer accesses each endpoint to receive the data in JSON format, through pagination:

https://awesomestore.com/clerk/product?key=insert_public&private_key=insert_private&page=1&limit=100
https://awesomestore.com/clerk/category?key=insert_public&private_key=insert_private&page=1&limit=100
https://awesomestore.com/clerk/order?key=insert_public&private_key=insert_private&page=1&limit=100

Integrations #

These use the webshop platform’s API to sync data, while snippets must be inserted manually into the webshop files. Examples include:

• Shopify
• BigCommerce
• Lightspeed

Integrations are hosted on Clerk.io’s servers, so while you can’t modify their code, they contain various configuration options from the Data page.

If we have an extension or integration for your platform, we recommend using it to simplify at least parts of the installation.

You can still choose to use them just for syncing data and then use the API or snippets for the frontend. Think of them as toolkits to make parts of the setup easier.

Choosing Your Setup #

Doing a Clerk.js integration is often the fastest and leaves the non-tech employees of your company with more control of the setup after the integration.

You also don’t have to worry about tracking and adding server load, as Clerk.js works in the frontend while the page is loading.

API setups are best if you have significant custom business logic you need to apply.

For example, if you are developing a B2B store with unique prices and catalogues for each logged-in customer, it’s easier to make API calls serverside, and apply the business logic after Clerk returns results.

Another case is if you need to do a switch from another API to Clerk. It’s often faster to simply replace API calls and remap parameters, than doing a Clerk.js installation.

Finally, if you are building an app, using the API is normally the best way of connecting it with Clerk.io, and it is generally the only way when the app does not support JavaScript.