The Clerk.io Developer Hub

Welcome to the Clerk.io developer hub. You'll find comprehensive guides and documentation to help you start working with Clerk.io as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    
Suggest Edits

product/add

Bulk add new / changed products to a store.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/product/add
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "private_key": "store_private_api_key"
          "products": [
                {
                  "id": 123,
                  "name": "Green Lightsaber",
                  "description": "Antiuque rebel lightsaber.",
                  "price": 99995.95,
                  "brand": "Je’daii",
                  "categories": [987, 654]
                },
                  {
                  "id": 789,
                  "name": "Death Star Deluxe",
                  "description": "Death Star. Guaranteed idiot proof. "
                  "price": 99999999999999.95,
                  "brand": "Imperial Inc.",
                  "categories": [345678]
                }
          ]}' \
     https://api.clerk.io/v2/product/add
A binary file was returned

You couldn't be authenticated

{
  "status": "ok"
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

private_key
string
required

Your store private API key.

products
array
required

List of the product objects to add. If the product already exists it will be overridden with the new data.

 
Suggest Edits

product/remove

Bulk remove products from a store.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/product/remove
curl https://api.clerk.io/v2/product/remove?key=store_api_key&private_key=store_private_key&products=123,456,789
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "private_key": "store_private_api_key"
          "products": [123, 456, 789]}' \
     https://api.clerk.io/v2/product/remove
A binary file was returned

You couldn't be authenticated

{
  "status": "ok"
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

private_key
string
required

Your store private API key.

products
array of mixed types
required

List of product IDs to be removed.

 
Suggest Edits

product/attributes

Loads the given attributes for the given products. See the API documentation for Product Metadata to embed this with every avary call.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/product/attributes
curl http://api.clerk.io/v2/product/remove?key=store_api_key&products=123,456,789&attributes=id,name,price
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "products": [123, 456, 789],
          "attributes": ["id", "name", "price"]}' \
     http://api.clerk.io/v2/product/attributes
A binary file was returned

You couldn't be authenticated

[
  {
    "id": 123,
    "name": "Wombat Wand",
    "price": 14.95
  },
    {
    "id": 123,
    "name": "Green Light Saber",
    "price": 99995.95
  },
    {
    "id": 789,
    "name": "Death Star Deluxe",
    "price": 99999999999999.95
  }
]
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

products
array of mixed types
required

List of product IDs to be removed.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details. If none is provided all available attributes will be returned.

language
string

The language if the store is using multiple languages. If not provided the most used language in the store will be used.

 
Suggest Edits

product/facets

Loads the facet groups available for the given products and attributes.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/product/facets
curl http://api.clerk.io/v2/product/facets?key=store_api_key&products=123,456,789&attributes=brand,price
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "products": [123, 456, 789],
          "attributes": ["id", "name", "price"]}' \
     http://api.clerk.io/v2/product/attributes
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "facets": {
    "categories": [
      {
        "count": 2,
        "type": "unit",
        "name": "Imperial Inc.",
        "value": "Imperial Inc."
      },
      {
        "count": 1,
        "type": "unit",
        "name": "Je’daii",
        "value": "Je’daii"
      }
    ],
    "price": [
      {
        "max": 49.0,
        "type": "range",
        "name": "0 - 49",
        "min": 0.0
      },
      {
        "max": 99.0,
        "type": "range",
        "name": "50 - 99",
        "min": 50.0
      },
      {
        "max": 750,
        "type": "range",
        "name": "> 100",
        "min": 100
      }
    ]
  }
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

products
array of mixed types

List of product IDs to be removed. If not provided facets will be computed for all products.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details. If none is provided all available attributes will be returned.

 
Suggest Edits

log/sale

Log a sale / order made by a user.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/log/sale
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "sale": 567,
          "products": [
            {
              "id": 1,
              "price": 99.95,
              "quantity": 2
            }, 
            {
              "id": 33,
              "price": 14.00,
              "quantity": 2
            }
          ],
          "customer": 1234,
          "email": "theone@matrix.com",
          "visitor":  "a1d0c6e83f027327d8461063f4ac58a6"}' \
       https://api.clerk.io/v2/log/sale
curl https://api.clerk.io/v2/log/sale?key=store_api_key&sale=123456&email=john@doe.com&products=123,456
A binary file was returned

You couldn't be authenticated

{
  "status": "ok"
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

sale
mixed type
required

ID of the order / sale.

products
array
required

List of products in the order. Can be a simple list of product IDs or a list of objects with ID, price and quantity.

customer
string

ID of the customer who made the order / sale.

email
string

The email of the customer who mae the order / sale.

visitor
string

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

 
Suggest Edits

log/click

Log a click on a product from Clerk.io

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/log/click
curl https://api.clerk.io/v2/log/click?key=store_api_key&product=123&visitor=unique_visitor_id
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "product": 123,
          "visitor": "unique_visitor_id"}' \
       https://api.clerk.io/v2/log/click
A binary file was returned

You couldn't be authenticated

{
  "status": "ok"
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

product
mixed type
required

ID pf the clicked product.

visitor
string
required

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

 
Suggest Edits

log/email

Associate an email with a visitor.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/log/email
curl https://api.clerk.io/v2/log/email?key=store_api_key&email=john@doe.com&visitor=unique_visitor_id
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "product": 123,
          "visitor": "unique_visitor_id"}' \
       https://api.clerk.io/v2/log/click
A binary file was returned

You couldn't be authenticated

{
  "status": "ok"
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

email
string
required

The visitors email.

visitor
string
required

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

 
Suggest Edits

search/predictive

"Search As You Type" API that predicts the given unfinished query and returns products matching it.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/search/predictive
curl http://api.clerk.io/v2/search/predictive?key=store_api_key&query=blue+running+sho&limit=6
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "query": "blue running sho",
          "language": "english",
          "limit": 6,
          "visitor": "unique_visitor_id",
          "exclude": [42],
          "filter": "price > 100",
          "labels": ["Search As You Type"]}' \
     http://api.clerk.io/v2/search/predictive
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [123, 456, 789]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

query
string
required

The search query.

limit
int32
required

Number of results to be returned. Maximum 10.

language
string

The language if the store is using multiple languages. If not provided the most used language in the store will be used.

filter
string

A attribute filter to filter the result. See API documentation on Filters for details.

exclude
array of mixed types

Array of product IDs to be excluded from the result. See API documentation on Filters for details.

visitor
string

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

labels
array of strings

A list of one or more text labels, used to track the labels performance in Analytics.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details.

 
Suggest Edits

search/categories

Category search API.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/search/categories
curl http://api.clerk.io/v2/search/categories?key=store_api_key&query=blue+running+sho&limit=6
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "query": "blue running sho",
          "language": "english",
          "limit": 6,
          "visitor": "unique_visitor_id"}' \
     http://api.clerk.io/v2/search/categories
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [123, 456, 789],
  "categories": [
    {
      "id": 123,
      "name": "Wommens Runing Shoes",
      "url": "http://super-store.com/wommens-running-shoes/"
    },
    {
      "id": 456,
      "name": "Wommens Runing Shoes / Nike",
      "url": "http://super-store.com/wommens-running-shoes-nike/"
    }
  ]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

query
string
required

The search query.

limit
int32
required

Number of results to be returned. Maximum 10.

language
string

The language if the store is using multiple languages. If not provided the most used language in the store will be used.

visitor
string

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

 
Suggest Edits

search/suggestions

Auto-complete the customer's search query as they type.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/search/suggestions
curl http://api.clerk.io/v2/search/suggestions?key=store_api_key&query=blue+running+sho&limit=6
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "query": "blue running sho",
          "language": "english",
          "limit": 6,
          "visitor": "unique_visitor_id"}' \
     http://api.clerk.io/v2/search/suggestions
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [
    "blue running shoes",
    "blue running shoes men",
    "blue running shoes women",
    "blue running shoes kids"
  ]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

query
string
required

The search query.

limit
int32
required

Number of results to be returned. Maximum 10.

language
string

The language if the store is using multiple languages. If not provided the most used language in the store will be used.

visitor
string

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

 

Suggest queries the customer could be searching for given the current typed query.

Suggest Edits

recommendations/currently_watched

The products other store visitors are currently looking at.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/recommendations/currently_watched
curl http://api.clerk.io/v2/recommendations/currently_watched?key=store_api_key&limit=30
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "limit": 30,
          "visitor": "unique_visitor_id",
          "exclude": [42],
          "filter": "price > 100",
          "labels": ["Search"]
          "facets": ["categories", "brands"]}' \
     http://api.clerk.io/v2/recommendations/currently_watched
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [123, 456, 789, ...]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

limit
int32
required

Number of results to be returned.

filter
string

A attribute filter to filter the result. See API documentation on Filters for details.

exclude
array of mixed types

Array of product IDs to be excluded from the result. See API documentation on Filters for details.

visitor
string

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

labels
array of strings

A list of one or more text labels, used to track the labels performance in Analytics.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details.

 
Suggest Edits

recommendations/keywords

Products based on content such as blogs, news or content pages.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/recommendations/keywords
curl http://api.clerk.io/v2/recommendations/keywords?key=store_api_key&limit=30
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "limit": 30,
          "visitor": "unique_visitor_id",
          "exclude": [42],
          "filter": "price > 100",
          "labels": ["Search"]
          "facets": ["categories", "brands"]}' \
     http://api.clerk.io/v2/recommendations/currently_watched
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [123, 456, 789, ...]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

keywords
string
required

The keywords (ie. content title) to base the recommendations upon.

limit
int32
required

Number of results to be returned.

filter
string

A attribute filter to filter the result. See API documentation on Filters for details.

exclude
array of mixed types

Array of product IDs to be excluded from the result. See API documentation on Filters for details.

visitor
string

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

labels
array of strings

A list of one or more text labels, used to track the labels performance in Analytics.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details.

 
Suggest Edits

recommendations/complementary

The products that customers are most likely to buy with a given product or multiple products.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/recommendations/complementary
curl http://api.clerk.io/v2/recommendations/complementary?key=store_api_key&products[]=123&limit=30
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "products": [123], 
          "limit": 30,
          "visitor": "unique_visitor_id",
          "exclude": [42],
          "filter": "price > 100",
          "labels": ["Search"]
          "facets": ["categories", "brands"]}' \
     http://api.clerk.io/v2/recommendations/complementary
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [123, 456, 789, ...]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

products
array of mixed types
required

Product ID(s) for the products you want complementary products for.

limit
int32
required

Number of results to be returned.

filter
string

A attribute filter to filter the result. See API documentation on Filters for details.

exclude
array of mixed types

Array of product IDs to be excluded from the result. See API documentation on Filters for details.

visitor
string

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

labels
array of strings

A list of one or more text labels, used to track the labels performance in Analytics.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details.

 
Suggest Edits

recommendations/substituting

The products that customers are most likely to buy instead of a given product or multiple products.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/recommendations/substituting
curl http://api.clerk.io/v2/recommendations/substituting?key=store_api_key&products[]=123&limit=30
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "products": [123], 
          "limit": 30,
          "visitor": "unique_visitor_id",
          "exclude": [42],
          "filter": "price > 100",
          "labels": ["Search"]
          "facets": ["categories", "brands"]}' \
     http://api.clerk.io/v2/recommendations/substituting
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [123, 456, 789, ...]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

products
array of mixed types
required

Product ID(s) for the products you want substituting products for.

limit
int32
required

Number of results to be returned.

filter
string

A attribute filter to filter the result. See API documentation on Filters for details.

exclude
array of mixed types

Array of product IDs to be excluded from the result. See API documentation on Filters for details.

visitor
string

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

labels
array of strings

A list of one or more text labels, used to track the labels performance in Analytics.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details.

 
Suggest Edits

recommendations/category/trending

The products in a given category (and subcategories) that are growing the most in popularity amongst customers right now.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/recommendations/category/trending
curl http://api.clerk.io/v2/recommendations/category/trending?key=store_api_key&category=123&limit=30
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "category": 123, 
          "limit": 30,
          "offset": 60,
          "visitor": "unique_visitor_id",
          "exclude": [42],
          "filter": "price > 100",
          "labels": ["Search"]
          "facets": ["categories", "brands"]}' \
     http://api.clerk.io/v2/recommendations/category/trending
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [123, 456, 789, ...]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

category
mixed type
required

Category ID for the category you want popular products for.

limit
int32
required

Number of results to be returned.

offset
int32

Offset into the result. See pagenation docs for a deeper specification on how to use pagenation.

filter
string

A attribute filter to filter the result. See API documentation on Filters for details.

exclude
array of mixed types

Array of product IDs to be excluded from the result. See API documentation on Filters for details.

facets
array of strings

List of facets to be returned for the products in the result. See API documentation on Facets for details.

visitor
string

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

labels
array of strings

A list of one or more text labels, used to track the labels performance in Analytics.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details.

 
Suggest Edits

recommendations/visitor/history

The history of a visitor's on-site activity.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/recommendations/visitor/history
curl http://api.clerk.io/v2/recommendations/visitor/history?key=store_api_key&visitor=unique_visitor_id&limit=30
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "visitor": "unique_visitor_id",
          "limit": 30,
          "exclude": [42],
          "filter": "price > 100",
          "labels": ["Search"]
          "facets": ["categories", "brands"]}' \
     http://api.clerk.io/v2/recommendations/visitor/history
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [123, 456, 789, ...]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

visitor
string
required

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

limit
int32
required

Number of results to be returned.

filter
string

A attribute filter to filter the result. See API documentation on Filters for details.

exclude
array of mixed types

Array of product IDs to be excluded from the result. See API documentation on Filters for details.

labels
array of strings

A list of one or more text labels, used to track the labels performance in Analytics.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details.

 
Suggest Edits

recommendations/visitor/complementary

The products that a specific visitor is most likely to buy right now based on their on-site activity.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/recommendations/visitor/complementary
curl http://api.clerk.io/v2/recommendations/visitor/complementary?key=store_api_key&visitor=unique_visitor_id&limit=30
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "visitor": "unique_visitor_id",
          "limit": 30,
          "exclude": [42],
          "filter": "price > 100",
          "labels": ["Search"]
          "facets": ["categories", "brands"]}' \
     http://api.clerk.io/v2/recommendations/visitor/complementary
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [123, 456, 789, ...]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

visitor
string
required

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

limit
int32
required

Number of results to be returned.

filter
string

A attribute filter to filter the result. See API documentation on Filters for details.

exclude
array of mixed types

Array of product IDs to be excluded from the result. See API documentation on Filters for details.

labels
array of strings

A list of one or more text labels, used to track the labels performance in Analytics.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details.

 
Suggest Edits

recommendations/visitor/substituting

The products that a specific visitor is most likely to buy as alternatives to their on-site activity.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/recommendations/visitor/substituting
curl http://api.clerk.io/v2/recommendations/visitor/substituting?key=store_api_key&visitor=unique_visitor_id&limit=30
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "visitor": "unique_visitor_id",
          "limit": 30,
          "exclude": [42],
          "filter": "price > 100",
          "labels": ["Search"]
          "facets": ["categories", "brands"]}' \
     http://api.clerk.io/v2/recommendations/visitor/substituting
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [123, 456, 789, ...]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

visitor
string
required

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

limit
int32
required

Number of results to be returned.

filter
string

A attribute filter to filter the result. See API documentation on Filters for details.

exclude
array of mixed types

Array of product IDs to be excluded from the result. See API documentation on Filters for details.

labels
array of strings

A list of one or more text labels, used to track the labels performance in Analytics.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details.

 
Suggest Edits

recommendations/customer/history

The history of a customer's on-site activity.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/recommendations/customer/history
curl http://api.clerk.io/v2/recommendations/customer/history?key=store_api_key&customer=customer_id&limit=30
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "visitor": "customer_id",
          "limit": 30,
          "exclude": [42],
          "filter": "price > 100",
          "labels": ["Search"]
          "facets": ["categories", "brands"]}' \
     http://api.clerk.io/v2/recommendations/customer/history
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [123, 456, 789, ...]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

customer
mixed type
required

The customers ID.

limit
int32
required

Number of results to be returned.

filter
string

A attribute filter to filter the result. See API documentation on Filters for details.

exclude
array of mixed types

Array of product IDs to be excluded from the result. See API documentation on Filters for details.

visitor
string

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

labels
array of strings

A list of one or more text labels, used to track the labels performance in Analytics.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details.

 
Suggest Edits

recommendations/customer/complementary

The products that a specific customer is most likely to buy right now based on their order history.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/recommendations/customer/complementary
curl http://api.clerk.io/v2/recommendations/customer/complementary?key=store_api_key&customer=customer_id&limit=30
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "visitor": "customer_id",
          "limit": 30,
          "exclude": [42],
          "filter": "price > 100",
          "labels": ["Search"]
          "facets": ["categories", "brands"]}' \
     http://api.clerk.io/v2/recommendations/customer/complementary
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [123, 456, 789, ...]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

customer
mixed type
required

The customers ID.

limit
int32
required

Number of results to be returned.

filter
string

A attribute filter to filter the result. See API documentation on Filters for details.

exclude
array of mixed types

Array of product IDs to be excluded from the result. See API documentation on Filters for details.

visitor
string

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

labels
array of strings

A list of one or more text labels, used to track the labels performance in Analytics.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details.

 
Suggest Edits

recommendations/customer/substituting

The products that a specific customer is most likely to buy right now as replacements for their order history.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/recommendations/customer/substituting
curl http://api.clerk.io/v2/recommendations/customer/substituting?key=store_api_key&customer=customer_id&limit=30
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "visitor": "customer_id",
          "limit": 30,
          "exclude": [42],
          "filter": "price > 100",
          "labels": ["Search"]
          "facets": ["categories", "brands"]}' \
     http://api.clerk.io/v2/recommendations/customer/substituting
A binary file was returned

You couldn't be authenticated

{
  "status": "ok",
  "result": [123, 456, 789, ...]
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

customer
mixed type
required

The customers ID.

limit
int32
required

Number of results to be returned.

filter
string

A attribute filter to filter the result. See API documentation on Filters for details.

exclude
array of mixed types

Array of product IDs to be excluded from the result. See API documentation on Filters for details.

visitor
string

Visitor ID for the given visitor. See API documentation on Visitor Tracking for details.

labels
array of strings

A list of one or more text labels, used to track the labels performance in Analytics.

attributes
array of strings

Product attributes to be provided in the response. See API documentation on Product Metadata for details.

 
Suggest Edits

campaigns/embed

Render a recommendation onto a dynamic image for embedding dynamic content in a email.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/campaigns/embed
curl http://api.clerk.io/v2/campaigns/embed?key=store_api_key&email=john@doe.com&embed=reciept-email&n=0&v=1234567890
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "email": "john@doe.com",
          "embed": "reciept-email",
          "n": 0,
          "v": 1234567890}' \
     http://api.clerk.io/v2/campaigns/embed
A binary file was returned

You couldn't be authenticated

// Redirects to the dynamically generated image on success.

{
  "status": "ok"
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

email
string
required

The email of the customer to load the recommendation for.

embed
string
required

ID of the Hosted Template to be embedded.

n
int32
required

Loading the n-th product in the set of recommended products. n is 0-indexed.

v
string
required

Unique version number of the email (ideally a random number per email or else a campaign id or date string).

append
string

Append this string to the redirect link URL.

prepend
string

Prepend this string to the redirect URL.

 
Suggest Edits

campaigns/click

Redirect the customer to the product corresponding to the previously rendered image from campaigns/embed.

 

Query Auth

 Authentication is required for this endpoint.
gethttp://api.clerk.io/v2/campaigns/click
curl http://api.clerk.io/v2/campaigns/click?key=store_api_key&email=john@doe.com&embed=reciept-email&n=0&v=1234567890
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
          "email": "john@doe.com",
          "embed": "reciept-email",
          "n": 0,
          "v": 1234567890}' \
     http://api.clerk.io/v2/campaigns/click
A binary file was returned

You couldn't be authenticated

// Redirects to the product URL.

{
  "status": "ok"
}
{
  "status": "error",
  "message": "A message explaining the error.",
  "moreInfo": "http://help.clerk.io/error/{ERROR_ID}",
  "type": "ErrorType",
  "id": "{ERROR_ID}"
}

Query Params

key
string
required

You store API key.

email
string
required

The email of the customer to load the recommendation for.

embed
string
required

ID of the Hosted Template to be embedded.

n
int32
required

Loading the n-th product in the set of recommended products. n is 0-indexed.

v
string
required

Unique version number of the email (ideally a random number per email or else a campaign id or date string).

append
string

Append this string to the redirect link URL.

prepend
string

Prepend this string to the redirect URL.