Sending sales data from a POS/ERP systen #
For some webshops, it’s relevant to upload sales-data from other systems than the actual webshop, for example if you want to optimise the algorithm based on sales from a physical store, or B2B store.
Clerk.io does not differentiate between orders from various sources - as long as you can provide an ID, a timestamp and a list of products that were bought, they can be uploaded:
https://docs.clerk.io/reference/order-resource
You can upload the orders in oneof two ways:
- With a CSV file as explained here
- By implementing calls to our CRUD API, allowing you to send order data directly to your store in Clerk.io.
With a CSV file you will be able to manually upload your sales at times where you want to, without coding.
The recommended approach is to use the CRUD API, as that allows you to automate the task entirely.
Simply add a POST call to the /orders endpoint in your ERP system or webshop, run the job at regular intervals, e.g. once a month, and you will be able to use offline orders to boost your online recommendations and search results.
Currency conversion #
There a multiple ways of working with currency conversion in Clerk.io. A simple way to make it work is outlined below.
1. Sending the different prices in the feed #
Clerk needs to know the prices of each product in the different currencies. The easiest way to do this is to send them as a dict of formatted prices, with the currency symbol as they key, in your Data Feed.
Example:
JSON
"products": [
{
"id": 1,
"name": "Cheese",
"description": "A nice piece of cheese.",
"price": 100,
"list_price": 50,
"categories": [25, 42],
"image": "http://example.com/images/products/1.jpg",
"url": "http://example.com/product/1",
"prices_formatted": "{'USD':'$100', 'EUR':'€ 87.70', 'GBP':'£ 68.68'}"
},
{
"id": 2,
"name": "A pound of nuts",
"description": "That's a lot of nuts!",
"price": 150,
"categories": [1],
"image": "http://example.com/images/products/2.jpg",
"url": "http://example.com/product/2",
"prices_formatted": "{'USD':'$150', 'EUR':'€142', 'GBP':'£120'}"
}
]
2. Creating a Formatter #
In the tracking script inserted on every page of your shop, you can define JavaScript functions, that can be used inside of our templates.
Here you can define a function that takes your price-dict as argument, and returns the price for a specific currency, that you can choose which matches the place of the currency in the price-dict.
Make sure that your code replaces currency with the currently chosen currency from the frontend.
JavaScript
Clerk('config', {
key: 'Your_API_Key',
formatters: {
currency_selector: function (price_list) {
const currency = "EUR";
price_groups_obj = JSON.parse(price_list)
return price_groups_obj[currency];
}
}
});
3. Using the Formatter in Clerk Designs #
Lastly, you can use this function as part of your design.
HTML
<div class="price">
<span class="price">
{{ product.prices_formatted | currency_selector }}
</span>
</div>
Customer-specific prices #
If you need to display completely unique prices based on which customer is logged in, you need to setup an Event in Clerk.io that inserts the correct price before the products are rendered.
Events are Javascript functions that are run before or after Clerk.io shows products.
This method is possible to use if you can look up prices from your server, directly from a Javascript function, in the frontend based on a product ID and a customer ID.
For showing individual customer prices, the code should run right after the response.
General Example #
<span class="clerk" data-template="@home-page-popular"></span>
<script>
Clerk('on', 'response', function(content, data) {
console.log(data.result);
});
</script>
The function takes the argument data which is the entire response that Clerk.io sends back from the API.
Individual Customer Prices Example #
The most important part of the response is product_data which contains each attribute of the products Clerk.io sends back:
This data can be manipulated, so standard prices can be r eplaced with customer-specific ones before rendering.
A simple example of how to do this, can be seen here:
<span class="clerk" data-template="@home-page-popular"></span>
<script>
var customer_id = INSERT_CUSTOMER_ID;
Clerk('on', 'response', function(content, data) {
console.log(data.product_data)
for (i = 0; i < data.product_data.length; i++) {
var product = data.product_data[i];
var custom_price = FETCH_PRICE_FROM_SERVER(product.id,customer_id);
product.price = custom_price;
}
});
</script>
In the code, you need to replace 2 things:
INSERT_CUSTOMER_ID should be replaced by a code that inserts the ID of the customer currently logged in.
FETCH_PRICE_FROM_SERVER should be replaced by a Javascript Ajaxfunction that uses the product ID and a customer id to find the correct price.
The price is then assigned to the Clerk.io attribute price which can be displayed in your Design like this:
{% raw %} {{ price }} {% endraw %}
Using this method allows you to display completely unique prices, while still using our easy-to-use Javascript solution.
Customer group prices #
The setup of customer group prices consists of 4 steps:
Include the various prices in the feed
Fetch the current customer groups ID
Create a function to fetch the relevant price
Show the price in the Design
1. Include Prices in the Feed #
Start by adding an attribute to all products which contains all of the various pricing options, making sure to correlate each price to a particular customer group.
This can be sent as a string-encoded JSON dict
For example:
Prices
customer_group_prices = '{"GROUP1":179, "GROUP2": 140, "GROUP3": 100, "GROUP4":70}'
2. Fetch the Customer Group ID #
Implement a small script somewhere on the page which fetches the customer-group ID of the current customer to a JS variable.
The Customer Group ID should be equivalent to the list indice that its matching price is contained within. For example, if the price is located in customer_group_prices[2], then the ID should also be 2. For example:
Customer Group ID
<script type="text/javascript">
const customer_group = GROUP2;
</script>
3. Create a Function to Fetch the Price #
After including the price in the feed and fetching customer_group variable, you can create a TemplateFormatter which takes the customer_group_prices list as an argument and returns the relevant price.
As described above, you can now fetch the price from the specific customer group as the key in the price-dict based on the customer_group ID.
The function should be put directly into the _visitor-tracking script_, and in this example it is called final_price:
Formatters
<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
(function(w,d){
var e=d.createElement('script');e.type='text/javascript';e.async=true;
e.src=(d.location.protocol=='https:'?'https':'http')+'://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: 'O7UITkJIXqXibeQF9ONobiGGKYYKtbvh',
formatters: {
final_price: function (customer_group_prices) {
price_groups_obj = JSON.parse(customer_group_prices)
var return_price = price_groups_obj[customer_group_key];
return return_price;
}
});
};
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
4. Show the Price in the Template #
When the final_price formatter has been created, you can name it directly in your Design, along with the customer_group_prices list that you created in step 1:
Template function call
5. Creating Customer Group Pricing by Extending Clerk.js #
Putting together some of the steps in the above solutions, you have the option to create customer group pricing to reference in your designs by including them in your Clerk.js extension file.
You can create globals for your customer groups, and formatters to reference these groups in your Clerk.io Designs using code like the example below. Be sure to replace INSERT_GROUP_ID_HERE with your group IDs.
globals: {
customer_group_id: INSERT_GROUP_ID_HERE
},
formatters:{
final_price: function(standard_price,group_price1, group_price2){
var customer_group = INSERT_GROUP_ID_HERE;
if (customer_group = 1){
return group_price1;
}
else if (customer_group = 1){
return group_price2;
}
else (){
return standard_price;
}
}
}
Syncing with HTTP Auth #
Often HTTP authentication is used on staging sites to avoid unwanted visitors.
This will, in many cases block the Clerk importer as well and typically display a 401 Unauthorized error in the sync log.
You can easily verify the importer by inserting the authentication info in the import URL like below, in Data Sync at my.clerk.io:
http://USER:PASS@www.ewoksRus.com/JSONFEED
No tracked orders in the dashboard #
Clerk.io needs to continuously track sales from the webshop to keep results up-to-date with your customers’ behaviour.
However, some settings in a webshop may cause the sales-tracking to fail.
Below, you can find out how to debug the sales-tracking and see what the most common issues and solutions are.
Before you start #
Make sure that you have installed:
The Clerk.js tracking script on all pages
The Sales-tracking script on your Order Success page.
These are required to track sales in general.
Debugging #
In most cases, sales tracking fails due to errors in the visitor IDs or product IDs of the sale call that is send to Clerk after a purchase has been completed. To debug this, you’ll have to make a test order. However, in some cases it might be related to the sales tracking script itself and can debugged by looking at the logs in my.clerk.io => Data => Logs as described below.
Start by going to your Clerk.io Dashboard, and go to Data -> Logs.
If the sales-tracking is failing because of an error in your script, you will often be able to see the error in the top of the page.
Click Details to see more:
If you cannot see any errors in logs, the easiest way to identify other sales-tracking issues is to place a test order.
Debugging with a test order #
The below guide will use Chrome as an example to show how to debug sales tracking with a test order, but other browsers have similar features.
Start by putting a couple of products in the basket.
Proceed to Checkout.
Before placing the order, open your browsers Console.
Find Network, and narrow down results for " clerk".
Place the order, so you see the order confirmation page.
Click the call that starts with sale (normally sale?key=…) to see the details that are being sent to and received by the sales-tracking. By clicking Preview you can easily identify any errors that will cause sales to not be tracked.
Error 1: “Invalid Syntax In Argument: products” #
This error happens if the product IDs you send have a wrong syntax.
The most common errors are:
The product-IDs are string-encoded in the sales-tracking, but you are using Integers in Clerk.io or vice-versa
The list of product IDs contain text-formatting characters like this: “products”:[\“id”\:\“123-m”\]. The format should be pure JSON, to eliminate any formatting.
The product IDs send with the call do not exist in the data you have synced with Clerk.
Error 2: “Missing Argument X” #
This means that you are not sending all the data Clerk.io needs to track the sale.
Make sure you include all the [data-] attributes in the sales-tracking.
Error 3: Call is never made #
If you can’t see the call to sale even with both scripts installed, then something has caused the Clerk.js script to be loaded incorrectly. To identify if this is the problem, try this:
Start by opening the Console in your browser
Type in “Clerk”.
If Clerk.js has not been loaded correctly, you will see a ReferenceError:
Clerk is not impacting orders #
If you successfully track sales in my.clerk.io, but none of them are from Clerk.io, you might have an error in your visitor-tracking (click-tracking) setup.
Start by making sure that visitor-tracking works, by doing the following:
Click on any product through Clerk.io’s Search or Recommendations
Proceed to place an order containing this product
Login to my.clerk.io and go to Order Details
Wait for the Order to show up.
If visitor-tracking is working, you will see the value and impact from the product you added through Clerk.io, in Tracked Orders:
If you see no value added in the order you placed, the following sections show common errors that could cause this.
1. Custom API Setups Where Click-Tracking Has Not Been Enabled #
If you setup Clerk.io with a custom integration directly with the API, you need to actively enable visitor-tracking.
This guide shows how to enable it.
2. Wrong Product IDs Are Being Tracked #
For visitor-tracking to work, the click- and sales-tracking must track the same product ID’s as the ones we receive in the importer.
Usually if this doesn’t work its because you are tracking variant ID’s instead of main ID’s or simply tracking the SKU instead of the ID.
To check if this is the issue do the following:
1. Go to Order Details and click the ID of the order you placed:
2. If Clerk.io was not able to identify the product, you will only see the ID and an
image placeholder:
3. Go to Data -> Products in the side-menu and search for the name of
the product you added. Here you will be able to see the expected ID
for the product:
4. Use this to make sure that you track the correct ID’s in the sales-tracking.
3. Visitor ID Changes During Session #
Clerk.io uses a visitor ID to identify each individual visitor/customer, and track whether they purchase products through Clerk.io.
This Visitor ID is created automatically when using Clerk.js to do the setup.
This error is rare, but you can check the visitor ID by following these steps:
1. Open up your Network settings in the browser, and narrow down results to “clerk”.
2. Start by checking any of the “undefined” calls which are related to search or
recommendations.
3. In “payload” you can check the current Visitor ID. You will be able to do this for all calls associated with Clerk.io
4. Proceed to click the product, and place an order with this product.
5. On the Order Success page, check your Network again, and find the call
to " sale?". 6. Make sure that “visitor” in the “payload” here, matches the Visitor ID you saw
in step 3.
7. If the Visitor ID’s mismatch you need to make sure you do not accidentally change
them. A common cause for visitor ID’s changing, could be if you use Clerk.js 2 on your
webshop pages, but Clerk.js 1 on your Order Success page. Check through your pages to
make sure you are using the same type of script everywhere. Use the below screenshot
for reference.
If you are in doubt, please reach out to our support through Live-Chat.
Invalid API Endpoint console error #
Clerk.io’s Javascript library Clerk.js uses the specialised class “clerk”, to look for the embedcodes that are used to render results.
If you see the “Invalid API Endpoint” error in your browsers console, it usually means the class “clerk” has accidentally been used in your HTML somewhere.
For example:
To fix this, simply rename the class to something else. Any class except “clerk” can be used for styling:
Upgrading to Clerk.js 2 #
Clerk.js 2 is a faster and much more flexible version of our JavaScript library that makes installing Clerk.io on any webshop a breeze.
However, since the two versions work slightly differently, you need to follow these steps to successfully upgrade.
The two main differences in Clerk.js 2 is:
The Designs in my.clerk.io use the Liquid, but can also easily be created using the Design Editor.
The script must be inserted just before the tag in your webshops template.
Step 1: Converting Designs #
Since Clerk.js 2 has a different approach Designs, you need to create new ones.
You can create your Clerk.js 2 Designs in one of two ways:
1. Use the intuitive Design Editor to create new Designs, as described in the following points.
2. Convert your old Designs. Follow this guide to see how to do it.
1.1 Start by going to my.clerk.io -> Recommendations / Search -> Designs and click New Design:
1.2 Select the design type, the type of content and Name the design (we recommend adding " V2" so its obvious that you are using Clerk.js2).. Then click Create Design.
1.3. In the Design Editor, click any of the existing elements like the name, image, button etc. to edit it, or add new elements to the Design to add more information about products.
1.4. Click Publish Design when you are done, and go to Step 2 in the guide.
1.5. Lastly, go to Recommendations / Search -> Content and change your Clerk.io Content to use your new Design.
1.6. Click Update Content. This will temporarily cause them to not show up on your webshop, until you are done with Step 2. Choose the new Design for all Content that should be updated.
1.7. There! You are now ready to switch over to Clerk.js 2.
Step 2: Replacing the script #
2.1. Start by locating the template file that is used to show all pages of the webshop, and where the original Clerk.js script is found near the bottom.
2.2. Remove the old script from the file:
2.3. Next go to my.clerk.io -> Settings -> Tracking Code. This page now contains your Clerk.js 2 tracking code.
2.4. Copy this code and insert it just before the tag in the template:
2.5. Save your template.
Congratulations! You are now running on the much-improved Clerk.js 2 setup!
You can see the full documentation for Clerk.js 2 here: https://docs.clerk.io/docs/clerkjs-quick-start
Handling require.js #
This guide only applies when using Clerk.js 1.
In some setups, Require.js stops Clerk.js from loading, which means that no sliders or search results will be shown.
When this happens, the following error will be shown in your console:
Uncaught ReferenceError: Clerk is not defined
There are two ways to handle Require.js. Both approaches requires you to make changes to the tracking-script, that you have inserted in the bottom of all pages.
Include “clerk” in Require.js #
The best approach is trying to get Require.js to recognize Clerk.io.
You can do this by inserting require([‘clerk’], function() {}); in the bottom of the tracking script:
Ignoring Require.js #
If the above solution doesn’t work, its possible to ignore Require.js.
You can do this by inserting window.__clerk_ignore_requirejs = true;
in the top of the tracking script:
After using one of these approaches, Require.js will now be compatible with Clerk.io.
Uninstalling #
To uninstall Clerk.io from your webshop, you’ll need to remove the Visitor Tracking and Order Tracking scripts you originally added.
An example of the Visitor Tracking script to delete, located in a header file:
Next, you’ll need to remove the Order Tracking script from your custom platform webshop.
When you installed Clerk.io, you likely added Order Tracking to either a tracking script module or an order confirmation page within your theme files, or a tracking module in your store. Just like Visitor Tracking, you’ll simply need to remove the Order Tracking script from the theme file.
Example of Order Tracking location below:
