Objects

Foundation #

True personalization is only possible when it is consistent across every touchpoint.

Clerk.io’s unified data platform ensures that all tools share the same data, delivering a seamless, personalized experience - whether your customers are chatting, searching, browsing, or receiving emails.

Privacy #

Clerk.io’s data foundation is built with privacy in mind, allowing for great personalization without compromising on data security. We are cookieless by default and fully GDPR compliant.

The core of Clerk.io’s AI works on order and product data. It literally just needs to know what was bought, at which point in time, to show the vast majority of results.

By also sending the email address of customers, you allow for true personalization based on individual purchase history. This is recommended, but not required.

Layers #

When the AI shows results, it happens through 4 layers:

1. Data layer, containing the raw data like attributes for products and orders.

2. AI layer, where Clerk.io’s AI uses the connections in all of the data to predict results, based on which endpoint is used.

3. Merchandising layer, where Campaigns can influence the results.

4. Product layer, where Clerk’s API outputs the final results.

Below, you can read about the various data points that Clerk.io uses to power its AI.

Products #

These are at the core of Clerk.io’s AI. They are used to understand the structure of your catalogue and are the main driving force behind the extra conversions that Clerk.io helps you achieve.

Products have a number of mandatory attributes that are required for Clerk.io to work correctly, but apart from that, you can any attributes you have available in your eCommerce platform. The mandatory attributes are:

• id
• name
• description
• price
• image
• url
• categories
• created_at

Below is an example of a Product object:

 {
    "id": 135,
    "name": "Lightsaber",
    "description": "Antique Rebel Lightsaber",
    "price": 99995.95,
    "image": "https://galactic-empire-merch.com/images/a-r-lightsaber.jpg",
    "url": "https://galactic-empire-merch.com/antique-rebel-lightsaber",
    "created_at": 1622548800,
    "brand": "Je’daii",
    "categories": [987, 654],
    "sizes": ["M", "L", "XL"],
    "material": "Kyber Crystal",
    "color": "Green"
  }

Check the full specification of Products here.

Categories #

These are used to group products together. While they are optional, they are highly recommended as it helps Clerk.io’s AI understand how your products are connected within your catalogue.

E.g., our Alternatives logic relies heavily on categories to understand what the closest similar items are and all Category related logics require them to be present.

Categories are sent to Clerk.io in the same way as products, but they have a different set of attributes.

You can send as many category attributes as you want for styling purposes (e.g., an image, a description, etc.), but only the mandatory attributes are used by Clerk.io for showing results.

The mandatory attributes are:

• id
• name
• subcategories
• url

Below is an example of a Category object:

{
    "id": 123,
    "name": "Lightsabers",
    "subcategories": [456, 789],
    "url": "https://galactic-empire-merch.com/lightsabers"
}

Check the full specification of Categories here.

Orders #

These are crucial to getting the best performance with Clerk.io as the AI uses order data to understand how customers interact with your products.

Everything from search results to Audience predictions use the order data to identify patterns in what customers are likely to do next.

The mandatory attributes are:

• id
• products
• time

In addition, we highly recommend sending the attribute email, which contains the customer’s email address, allowing for personalisation and Audience segmentation.

It’s also possible to send the status of an order, including info on Parcels, allowing your customers to ask about their parcels when using Clerk.io Chat.

Below is an example of an Order object:

{
    "id": 5434,
    "products": [123, 456],
    "time": 1622548800,
    "email": "luke@skywalker.com",
    "status": "DELIVERED"
}

Check the full specification of Orders here.

Pages #

While these are optional, they are highly recommended as they allow Clerk.io to work with your blogs, articles, and other content pages.

These can be shown in search results, have recommendations shown on their pages, and be included as relevant content banner when customers browse products or categories.

The mandatory attributes are:

• id
• type
• url
• title
• text

Apart from these, we also recommend sending an image attribute to make your Pages recommendations more visually appealing, which often leads to more clicks.

Below is an example of a Page object:

{
    "id": 123,
    "type": "blog",
    "url": "https://galactic-empire-merch.com/blog/lightsaber-history",
    "title": "The History of Lightsabers",
    "text": "Lightsabers have been around for centuries, learn about their history here."
}

Check the full specification of Pages here.

Customers #

These are optional, but recommended as it allows you to use Clerk.io’s Audience tool as a CDP. The Customer object contains an ID or email address, along with any number of attributes you want to segment them on.

The ID or email address is used to connect the Customer data to any existing order data that already includes their ID or email address.

When sending the objects, Audience will automatically get a new option called Customer Data where you can segment on these attributes.

The only mandatory attribute for Customers is:

• id or email

Apart from this, we recommend sending any data points that are relevant to your marketing, like gender, age, interests, and more.

Below is an example of a Customer object:

{
    "id": 255,
    "email": "leia@royalty.com",
    "name": "Leia Organa",
    "gender": "Female",
    "age": 28,
    "interests": ["Rebellion", "Politics", "Leadership"]
}

Check the full specification of Customers here.