The Clerk.io Developer Hub

Welcome to the Clerk.io developer hub.

This is site is only technical specification for developers.

You'll find comprehensive guides and documentation to help you start working with Clerk.io at our Help Center

Get Started    

Data Feed Specification

This Is Only Needed For Platforms Without A Clerk.io Plugin

The data feed is only needed for platforms without an extension, following the custom setup guide.

See help.clerk.io for a list of all supported platforms

The first step of integrating Clerk.io with any store is to sync the stores product-, category- and sales-data with Clerk.io.

This is done via a data feed in JSON format as described in this document.

Remember: Always Use a JSON library to create the feed

Most programming languages have a built-in JSON library, that automatically parses and writes data in JSON. This means that you never have to manually type JSON.

Check the official JSON homepage, for a library for your programming language.

The overall structure of the feed is this:

{
  "products": [ ... ],
  "categories": [ ... ],
  "sales": [ ... ],

  "created": UNIX_TIME_STAMP,
  "strict": false
}
{ 
  "products": [
    {
      "id": 123,
      "name": "Green Lightsaber",
      "description": "Antiuque rebel lightsaber",
      "price": 99995.95,
      "image": "http://your-store.com/images/antique-rebel-lightsaber.jpg",
      "url": "http://your-store.com/antique-rebel-lightsaber",
      "brand": "Je’daii",
      "categories": [987, 654]
    },
    {
      "id": 789,
      "name": "Death Star Deluxe",
      "description": "Death Star - Guaranteed idiot proof",
      "price": 99999999999999.95,
      "image": "http://your-store.com/images/death-star.jpg",
      "url": "http://your-store.com/death-star",
      "brand": "Imperial Inc.",
      "categories": [345678]
    }
  ],

  "categories": [
    {
      "id": 1,
      "name": "Imperial Goods",
      "subcategories": [42, 25],
      "url": "http://your-store.com/imperial-goods"
    },
    {
      "id": 42,
      "name": "Tatooine",
      "subcategories": [],
      "url": "http://your-store.com/imperial-goods/tatooine"
    },
    {
      "id": 25,
      "name": "Coruscant",
      "subcategories": [],
      "url": "http://your-store.com/imperial-goods/coruscant"
    }
  ],

  "sales": [
    {
      "id": 123458,
      "customer": 789,
      "email": "vader@the-death-star.com",
      "products": [{"id":456,"quantity":1,"price":200.00}, {"id":789,"quantity":2,"price":120.00}],
      "time": 1389871120
    },

    {
      "id": 123456,
      "customer": 456,
      "email": "obi.wan@kenobi.me",
      "products": [{"id":456,"quantity":1,"price":200.00}, {"id":789,"quantity":2,"price":120.00},{"id":123,"quantity":2,"price":60.00}],
      "time": 1389870977
    },

    {
      "id": 123457,
      "customer": "",
      "products": [{"id":789,"quantity":2,"price":120.00}],
      "time": 1389871090
    },
  ],
    
  "customers": [
    {
      "id": 135,
      "name": "Luke Skywalker",
      "email": "luke@rebels.org",
      "gender": "male",
      "subscribed_to_newsletter": true
    },
    {
      "id": 1,
      "name": "Darth Vader",
      "email": "vader@empire.com",
      "gender": "male",
      "age": 45,
      "interests": ["loghtsaber", "force"],
      "subscribed_to_newsletter": false
    }
  ],
  
  "created": 1234567890,
  "strict": false
}

Here is a table of what each entry does:

Entry
Content

products

A list of all the products in the store.

categories

A list of all the categories in the store.

sales

A list of all orders made in the store.

customers

A list of you registred customers in your store.

created

Optional. A timestamp indicating when the feed was last updated. This is used for product versioning if real time product updates are pushed via the API.

strict

Optional. Should the feed be parsed in strict mode or nor. If set to true all values will be interpreted as is but if set to false string encoded numbers etc will be parsed to numbers etc. By default strict is set to false, and this setting is especially recommended to keep if you are using PHP.

The following sections describe the structure of products, categories and sales.

Null Values Not Welcome

Unchecked null values are a sure way for errors to sneak in over time. If an attribute does not exist for a given product, category or order simply just omit the attribute.

Products

A product is represented as a product object. A product object is a JSON object where each key, value pair corresponds to a product attribute name, attribute value.

All attribute names must be strings and values can be either bool, int, float, string or a list of the former.

A product can have any number of attributes but must at least contain the following marked as Required:

Attribute
Importance
Content

id

Required

The product ID.

name

Required

The product name.

description

Required

The product description.

price

Required

The product current selling price.

list_price

Optional

The product original list price.

image

Required

The full URL for the product image. This will be used for thumbnails when displaying products. We recommend a maximum image size of 200x200px.

url

Required

The full URL for the product page.

categories

Required

A list of the category IDs for the product categories.

brand

Optional

The product brand as a string.

sku

Optional

The product SKU (Stock Keeping Unit).

age

Optional

The number of days since the product was created.

on_sale

Optional

true if this product is on sale, else false.

gender

Optional

Is the product for a specific gender? Add that information.

color / colors

Optional

Color information about the product.

keywords

Optional

Keywords or synonyms that should be searchable for the product.

[
  {
    "id": 135,
    "name": "Green 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",
    "brand": "Je’daii",
    "categories": [987, 654]
  },
  {
    "id": 261,
    "name": "Death Star Deluxe",
    "description": "Death Star - Guaranteed idiot proof",
    "price": 99999999999999.95,
    "image": "https://galactic-empire-merch.com/images/death-star.jpg",
    "url": "https://galactic-empire-merch.com/death-star",
    "brand": "Imperial Inc.",
    "categories": [345678]
  }
]

Categories

A category is represented as a category object with the following entries:

Key
Importance
Content

id

Required

The category ID.

name

Required

The category name.

url

Required

The category URL.

subcategories

Required*

The IDs of the category's immediate subcategories.

[
  {
    "id": 1,
    "name": "Imperial Goods",
    "subcategories": [42, 25],
    "url": "https://galactic-empire-merch.com/imperial-goods"
  },
  {
    "id": 42,
    "name": "Tatooine",
    "subcategories": [],
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine"
  },
  {
    "id": 25,
    "name": "Coruscant",
    "subcategories": [],
    "url": "https://galactic-empire-merch.com/imperial-goods/coruscant"
  }
]

Sales

A sale/order is represented as a sale object with the following entries:

Key
Importance
Content

id

Required

The sale/order ID.

products

Required

The products in the order. Each product is an object with an ID, quantity, and unit price.

time

Required

The time of the order as a Unix Timestamp.

email

Required*

The customer email.

customer

Optional

The customer ID, if any.

*Note that email is required to use our Email and Audience products.

[
  {
    "id": 123458,
    "customer": 789,
    "email": "vader@the-death-star.com",
    "products": [{"id":456,"quantity":1,"price":200.00}, {"id":789,"quantity":2,"price":120.00}],
    "time": 1389871120
  }

  {
    "id": 123456,
    "customer": 456,
    "email": "obi.wan@kenobi.me",
    "products": [{"id":456,"quantity":1,"price":200.00}, {"id":789,"quantity":2,"price":120.00},{"id":123,"quantity":2,"price":60.00}],
    "time": 1389870977
  },

  {
    "id": 123457,
    "customer": "",
    "products": [{"id":789,"quantity":2,"price":120.00}],
    "time": 1389871090
  },
]

Orders are kept once synced

Orders are stored as a log and thus never deleted. After the first successful Data Sync, and when sales tracking is working, you can remove orders from the feed to reduce the feed file size.

Customers

Beta Users Only

This is a beta feature for accepted beta users only.

Each Customer is represented as a customer object where each key-value pair corresponds to a Customers attribute name and value. Just as for product objects, customer objects allow you to have any number attributes.

All attribute names must be strings, and values can be either bool, int, float, string or a list of the former.

A product can have any number of attributes but must at least contain the following marked as Required:

Key
Importance
Content

id

Required

The customer ID.

name

Required

The customers full name.

email

Required

The customers email.

zip

Optional

The customers zip code.

gender

Optional

The customers gender.

age

Optional

The customers age.

is_subscriber

Optional

Boolean indicating whether the customer has subscribed to newsletters.

is_b2b

Optional

Boolean indicating whether a customer is B2B or not.

[
  {
    "id": 135,
    "name": "Luke Skywalker",
    "email": "luke@rebels.org",
    "gender": "male",
    "zip": "1134",
    "is_subscriber": true,
    "is_b2b": "false"
  },
  {
    "id": 165,
    "name": "Darth Vader",
    "email": "vader@empire.com",
    "gender": "male",
    "age": 45,
    "interests": ["lightsaber", "force"],
    "is_subscriber": false,
    "is_b2b": true
  }
]

Data Security

Do this as the very last step

This is an optional feature, so skip this until your have made a full working implementation and are ready to go into production.

Your data is extremely business-sensitive so security is of the highest priority!

We recommend that the JSON feed only accepts an SSL encrypted connection and uses HTTP Authentication if possible.

In addition, these basic security measures provide an additional layer of security so you can verify that the request to download the feed is from a trusted source (ie. us). The system is based on a shared secret; your account Private API Key is found under your Account Settings.

All requests via HTTP or HTTPS are given two query parameters hash and salt. salt is just a random string used to salt the hash function. hash is a SHA512 hash computed from the Private API Key in the following way:

hash = SHA512(salt + private_key + str(int(floor(unix_timestamp() / 100))))

Where + is the concatenation operator and unix_timestamp() returns the current Unix Timestamp.

An example request could be the following URL:

https://example.com/clerk-product-feed.php?salt=f4Ke...A02X&hash=4DFF...340F

Thus by recomputing the hash you can verify that the request issuer knows your private key, and is trustworthy, so that the feed data can be provided safely.

Syncing your data feed

When your feed has the above structure you can upload it to Clerk.io by going to Data Sync in my.clerk.io.

Choose JSON as the sync method, paste the feed url and choose the language of the feed. Click Update Settings once you are done.

Afterwards, click Start Sync to synchronise the feed.

Integration configuration

Integration configuration

Data Feed Specification