Merchandising Cloud

/smart-collection/{slot}

Overview

Smart recommendation strategies use AI-powered algorithms to deliver personalized product suggestions based on customer behavior and product relationships. When recommendations adapt to individual browsing patterns and purchase history, you help improve product discovery and tend to enhance conversion rates through more relevant product suggestions that align with each customer's specific interests and needs.

AI-driven smart recommendations enable sophisticated merchandising that learns from customer interactions. This helps improve average order value and customer satisfaction by presenting products that genuinely match customer preferences, supporting better conversion optimization through intelligent product suggestions that evolve based on customer behavior patterns.

Endpoint

POST https://api-v3.findify.io/v3/smart-collection/{slot}

Authentication

Include your API key in the X-Key header:

X-Key: 2e963f3e-38bd-4c00-9636-c00e48945eb7

Path Parameters

Parameter	Type	Required	Description
`slot`	string	Yes	Collection handle

Request Parameters

Parameter	Type	Required	Default	Description
`t_client`	date-time	Yes	-	Timestamp when request is sent from the browser
`user`	object	Yes	-	User identification object
`user.uid`	string	Yes	-	User ID (max 32 characters)
`user.sid`	string	Yes	-	Session ID (max 32 characters)
`user.email`	string	No	-	User email address
`user.ip`	string	No	-	User IP address
`user.ua`	string	No	-	User agent string
`user.lang`	array of strings	No	-	User language preferences
`sort`	array of objects	No	-	Sort criteria
`sort[].field`	string	Yes	-	Field to sort by
`sort[].order`	string	Yes	-	Sort order (asc/desc)
`filters`	array of objects	No	-	Filter criteria
`filters[].name`	string	Yes	-	Filter name
`filters[].type`	string	Yes	-	Filter type
`filters[].values`	array of strings	Yes	-	Filter values
`offset`	integer	No	0	Result offset for pagination
`limit`	integer	No	24	Maximum number of results (max 120)
`callback`	string	No	-	JSONP callback function name
`log`	boolean	No	-	Enable logging
`rules`	array of objects	No	-	Custom rules

Response

Response Schema (200 OK)

The response contains product recommendations based on the smart collection algorithm:

Response Fields

Field	Type	Description
`meta`	object	Response metadata
`meta.rid`	string	Request ID for tracking
`meta.total`	integer	Total number of results
`meta.offset`	integer	Current offset
`meta.limit`	integer	Results per page
`items`	array of objects	Product items
`items[].id`	string	Product ID
`items[].title`	string	Product title
`items[].description`	string	Product description
`items[].price`	array of numbers	Product price
`items[].image_url`	string	Product image URL
`items[].product_url`	string	Product page URL
`facets`	array of objects	Available facets for filtering
`banner`	object	Banner configuration

Code Examples

Shell

curl --request POST \
  --url https://api-v3.findify.io/v3/smart-collection/test \
  --header "X-Key: 2e963f3e-38bd-4c00-9636-c00e48945eb7" \
  --header "Content-Type: application/json" \
  --data '{
    "user": {
      "lang": ["en-GB"],
      "uid": "test1",
      "sid": "ssid",
      "email": "test@test.com",
      "ip": "192.168.0.1",
      "ua": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36"
    },
    "t_client": 1484742065791,
    "sort": [{
      "field": "price",
      "order": "desc"
    }],
    "offset": 0,
    "limit": 20,
    "log": false
  }'

JavaScript (SDK)

Include the SDK from https://github.com/findify/javascript-sdk

var client = FindifySDK.init({
  key: '2e963f3e-38bd-4c00-9636-c00e48945eb7',
  user: {
    uid: 'test1',
    sid: 'ssid',
    email: 'test@test.com'
  },
  log: false
});
var request = {
  slot: 'test',
  sort: [{
    field: 'price',
    order: 'desc'
  }],
  offset: 0,
  limit: 20
};
client.collection(request).then(function (response) {
  console.log(response);
});

JavaScript (Node.js)

var request = require("request");
var options = {
  method: 'POST',
  url: 'https://api-v3.findify.io/v3/search',
  headers: {
    "X-key": "2e963f3e-38bd-4c00-9636-c00e48945eb7"
  },
  body: {
    user: {
      lang: ['en-GB'],
      uid: 'test1',
      sid: 'ssid',
      email: 'test@test.com',
      ip: '192.168.0.1',
      ua: 'Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36'
    },
    q: '1484742065791',
    t_client: 1484742065791,
    filters: [{
      name: 'category1',
      type: 'category',
      values: [{"value": "Dog Food"}]
    }],
    sort: [{
      field: 'price',
      order: 'desc'
    }],
    offset: 0,
    limit: 20,
    log: false
  },
  json: true
};
request(options, function(error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

PHP

<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure API key authorization: key
Swagger\Client\Configuration::getDefaultConfiguration()->setApiKey('X-Key', '2e963f3e-38bd-4c00-9636-c00e48945eb7');
$api_instance = new Swagger\Client\Api\DefaultApi();
$collection   = new \Swagger\Client\Model\CollectionRequest(array(
    'user' => array(
        'uid' => 'test1',
        'sid' => 'ssid',
        'email' => 'test@test.com',
        'ip' => '192.168.0.1',
        'ua' => 'Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36',
        'lang' => array(
            'en-US',
            'en-GB',
            'no'
        )
    ),
    't_client' => '1484741395471',
    'offset' => 0,
    'limit' => 20,
    'log' => false
));
try {
    $result = $api_instance->smartCollectionSlotPost('test', $collection);
    echo $result;
}
catch (Exception $e) {
    echo 'Exception when calling DefaultApi->smartCollectionSlotPost: ', $e->getMessage(), PHP_EOL;
}
?>

Product Recommendations:

Conversion Optimization: