Sync
Starting a sync #
You can always start a full sync from my.clerk.io by going to Data > Configuration and clicking Start New Data Sync.
This will import all of the latest data from your webshop, using the sync method you have selected.
After you click Start New Data Sync, Data Sync shows the expected wait and queue status before processing begins:
- Starts in [time] means the sync is waiting for the cooldown to finish.
- Slight delay in the download queue means 20–99 jobs are ahead.
- Moderate delay in the download queue means 100–499 jobs are ahead.
- Significant delay in the download queue means 500 or more jobs are ahead.
- Data sync starting… means there is no meaningful delay.
Sync status #
Open Data > Configuration to see imported counts for products, categories, pages, customers and orders.
Data synchronization and data analysis have separate status sections. Each shows the latest outcome and timing information. Synchronization fetches data from your webshop; analysis processes the data for Clerk.io.
Synchronization also shows its duration and the average duration of a full sync. Use this information to judge how long a run normally takes.
Use Start new data sync or Start new data analysis beside the corresponding status to run that action. While a run is starting or running, follow the progress shown in its status area.
Settings #
These settings let you configure access to your webshop and how data is fetched. Common Sync settings, including Sync Time, follow Sync platform and appear before the importer-specific settings.
Sync method #
Clerk comes with a number of integrations and sync methods, making it possible to sync from any eCommerce platform. The integrations we build use their own sync method for the platforms like Shopify, Magento, WooCommerce, and so on.
It’s also possible to choose Demo Data as the sync method. With this, Clerk will sync a predefined dataset that you can use for testing. This is useful if you just want to play around with my.clerk.io and our API before starting a real setup.
Sync Time #
This setting lets you choose 1-hour increments when the sync should run. By choosing a time, the sync will only run within that timeframe in UTC time. This is useful if you want to save server capacity during high-load hours, and only sync when the server is less busy.
By default, it’s set to When Needed (Recommended) which will run the sync regularly depending on how long it takes to load your data. If it takes less than 10 minutes, the sync might run every hour, while syncs taking 60+ minutes might only run once a day.
Import #
You can decide exactly which data points to import by selecting either Yes or No to each one of:
- Products
- Categories
- Orders
- Customers
- Pages
Clerk requires products and categories to work correctly, and it’s strongly recommended to also import orders, as these are the main driving force behind Clerks results.
Pages imported through the data sync will overwrite any changes made in my.clerk.io to those synced pages the next time pages are synced.
Pages that you upload manually in Data > Pages are treated as protected and are not overwritten by the data sync.
AI Importers #
AI Importers let you build a custom integration from scratch, without any predefined configuration. If your platform exposes an API, Clerk.io can connect to it.
The setup is handled through Ask Clerk.io. Describe which platform you want to connect to, and Ask Clerk.io guides you through credentials, builds the importer, tests the connection, and hands off to Data Sync with the full configuration in place.
You can also handle importer and sync questions in the same Ask Clerk.io conversation. If a sync needs credentials or another decision, Ask Clerk.io explains what it needs before continuing.
AI Importers are standalone integrations. If your store runs on Shopify, for example, and you want to import additional data that the standard Shopify importer does not cover, you set up a new AI Importer configured to talk to Shopify directly.
That AI Importer then handles everything: the standard data as well as any extra fields you need.
Once the connection is established, you can extend what is imported — adding extra attributes, pulling in data from third-party integrations, or adjusting the logic to fit your catalogue — all through Ask Clerk.io.
To test or change an existing AI importer, use Test importer or Edit importer in Data > Configuration. See Manage an importer for the full workflow.
Read more about setup in AI Integration.
Multiple Importers #
Multiple Importers let you combine different sync methods for different data types in a single store setup.
This is useful when your data lives in more than one place. You might import products, categories, and orders from Magento 1, while importing customer data from a segmentation platform and pages from WordPress.
Each data type is handled by one importer at a time — you cannot import the same type from two sources simultaneously. But you have full control over which importer is responsible for each type.
Open Data > Configuration and find Your importers below the common Sync settings. Select an existing importer tab to show its settings. The other tabs remain available so you can switch back.
Use the separate Add importer dropdown to choose the type of importer you want to add. Settings and actions belong to the selected importer.
For each importer, you can configure which data types it should import. If a data type is assigned to one importer, it should not also be enabled in another — each type should have exactly one source.
Products and categories are required for Clerk.io to function correctly. Make sure at least one importer is responsible for each of these.
Troubleshoot a run #
From a sync or analysis status section, open its log-details action to view that specific run in Developers > Logs. You do not need to find the run in the full log list.
See Developer Logs for filters, log periods and event details.
Whitelisting IP Address #
If your server has an IP lock, you need to whitelist the IP address of Clerks Data Sync system to allow access to your data.
The IP address is 52.57.0.11
This IP is subject to change. If Data Sync responds with a 403 or similar error, simply come back to this page to find the current IP address.
Realtime updates #
This is the best way to keep Clerk up-to-date with your webshop without delay. While the full data sync is great for loading large amounts of data at regular intervals, realtime updates are used to send smaller changes as they happen.
Most of our extensions and integrations have them built-in, with no extra setup needed. For any other platforms, they can be set up through our CRUD API.
With realtime updates enabled, Clerk is able to fetch changes like a simple price update, but also add or remove products entirely.
This means Clerk will not have to wait for a full sync every time you make smaller changes, which keeps your setup fully up-to-date immediately.
When adding a product through the real-time sync, it will appear on your webshop instantly after it shows in the Clerk.io backend.
When a product is added through the real-time sync, it’s immediately visible in Search, Recommendations and Email, but the product ranking is not included. This means that it might not show as a popular product until the full data sync runs.
CSV Files #
This is a special sync method that can be used for demoing Clerk.io’s features through a Live Demo by uploading a one-time export of your catalogue. You can use it by choosing One-Time CSV Upload from the Sync method dropdown.
The upload screen shows a real-time progress bar while Clerk.io processes the files. The processing can continue after the file transfer finishes, so wait until the progress is complete before continuing.
Generate CSV files for at least your products, categories, and orders and, if you want to see the full capabilities of Clerk, also your customers and pages.
Download a zip file containing CSV template files for all data types.
All files use comma separation. Any value that contains a comma must be wrapped in double quotes, for example "1,2,3" for a list of IDs.
Products #
Each row represents one product.
| Field | Required | Description |
|---|---|---|
id | Required | Unique product identifier |
Name | Required | Product name |
description | Required | Product description |
price | Required | Current selling price |
image | Required | Full URL to the product image |
url | Required | Full URL to the product page |
categories | Required | Comma-separated IDs of categories the product belongs to. Use quotes when listing multiple: "1,2,3" |
list_price | Optional | Original price before any discounts |
Vendor | Optional | Brand or vendor name |
Tags | Optional | Comma-separated product tags |
Status | Optional | Product status, e.g. active |
Categories #
Each row represents one category.
| Field | Required | Description |
|---|---|---|
id | Required | Unique category identifier |
name | Required | Category name |
url | Required | Full URL to the category page |
subcategories | Required | Comma-separated IDs of child categories. Leave blank if there are none |
image | Optional | Full URL to the category image |
description | Optional | Category description |
Orders #
Each row represents one line item. An order with multiple products spans multiple rows, all sharing the same id.
| Field | Required | Description |
|---|---|---|
id | Required | Order identifier. Repeated across rows for orders with multiple products |
time | Required | Unix timestamp of when the order was placed |
Product_Id | Required | ID of the product purchased in this line item |
Email | Recommended | Customer email address, used for personalisation |
quantity | Recommended | Quantity of the product in this line item |
price | Recommended | Price paid for the product in this line item |
Customers #
Each row represents one customer. Either id or Email must be present. Any extra columns you include are imported as custom attributes and can be used for audience segmentation.
| Field | Required | Description |
|---|---|---|
id | Required* | Unique customer identifier |
Email | Required* | Customer email address |
name | Optional | Full name |
First Name | Optional | First name |
Last Name | Optional | Last name |
subscribed | Optional | Set to true to sync an existing subscriber with Clerk.io |
* At least one of id or Email is required.
To sync existing subscribers, include their email address and a subscribed column set to true. This imports the customer with the attribute subscribed: true so they can receive email marketing from Clerk.io.
Email,subscribed
luke@example.com,true
Pages #
Each row represents one content page.
| Field | Required | Description |
|---|---|---|
id | Required | Unique page identifier |
type | Required | Page type, e.g. blog or article |
url | Required | Full URL to the page |
title | Required | Page title |
text | Required | Full text content of the page |
image | Optional | Full URL to the page image |