Shoptimiza Client API

Fetch recommendations for a given product

Fetching recommendations is as simple as making a JSONP HTTP request like the following

GET https://api.shoptimiza.com/v1/re/$API_KEY/$PRODUCT_ID?callback=$CALLBACK&r=$RANDOM

Were:

$API_KEY is your site API Key
$PRODUCT_ID is the product ID
$CALLBACK is a javascript callback function
$RANDOM random value to prevent browser caching. It can be something simple like Date.now()

Example

<script>
function display(recommendations){
	// do your magic here
	console.log(recommendations);
}
</script>

<script src="https://api.shoptimiza.com/v1/re/$API_KEY/$PRODUCT_ID?callback=display&r=$RANDOM"></script>

Our response to the script call will look like

/**/ typeof display === 'function' && display(some data here);

Response format

You should not cache the results. We might conduct A/B testings or customize the results for a given user.

The response is a JSON object with:

alsoBought an array of product IDs that have been also bought along with $PRODUCT_ID. You can use this data to create a "Customers who bought this item also bought" widget
boughtTogether an array of product IDs that have been frequently bought together with $PRODUCT_ID. It represents a bundle.
key original $PRODUCT_ID

Here is an example:

// Expected response
{
    "alsoBought": ["2", "4"],
    "boughtTogether": ["5", "3"],
    "key": "5"
}

It is important to note that boughtTogether first item is always the requested product id.

Tracking

We track impressions, clicks and conversions. We use those data points to improve your site recommendations. Please add our analytics code even if you track those events with other providers i.e. Google Analytics.

First thing is to include our tag inside the <head> tag:

<head>
...
	<script>
	(function(s,h,o,p,t,m,z){s["ShoptimizaAnalyticsObject"]=t;  
	s[t]=s[t]||function(){(s[t].q=s[t].q||[]).push(arguments)};  
	s[t].start=1*new Date;m=h.createElement(o);z=h.getElementsByTagName(o)[0];  
	m.async=1;m.src=p;z.parentNode.insertBefore(m,z)})
	(window,document,"script","https://cdn.shoptimiza.com/analytics.js","sa");
	// set your API Key
	sa('create', '$API_KEY');
	// enable last product views and other features related with 
	// what was this user doing
	sa('set','memento',true);
	</script>
...
</head>

Were $API_KEY is your Shoptimiza API Key.

Click tracking

In order to improve your recommendations we need to know about clicks and conversions.
The following example shows how to integrate your recommendations HTML with Shoptimiza click tracking:

<head>
...
// Shoptimiza analytics tag
...
</head>
<body>
....
<script>
function getHTMLForRecommendations(recommendations){
	/* this function should send a list of product ids to your server.
	 * Your server should return HTML
	 */
}
function display(recommendations){
	var htmlWidget = getHTMLForRecommendations(recommendations); // build your html
	var container = document.createElement('div');
	container.innerHTML = html;
	$(container).on('click', 'a', function (e) {
		var productId = /* get your product id. I.e use data attributes on your links*/;
		sa('track', 'click', productId);
	});
	// append your container to DOM
}
</script>

<script async src="https://api.shoptimiza.com/v1/re/$API_KEY/$PRODUCT_ID?callback=&display&r=$RANDOM"></script>

What did just happened?
We loaded the recommendations and created an html to represent our recommendations with getHTMLForRecommendations. After that we have created a div container to host the widget. That HTML could look like:

<ul>
    <li class="product">
        <a data-click-id="2" href="/products/2">
            <img src="...">
            <p>
            <span>product 2 description</span><br>
            <span>XX,XX€</span>
            </p>
            </a>
    </li>
    ... more products
</ul>

The line $(container).on('click', 'a', function (e) {... has captured all clicks on a elements. When the user clicks on them sa, our analytics script, will notify Shoptimiza.

Conversion tracking

Conversion tracking is easier than click tracking. Just send a conversion event when you confirm a purchase order

// yourdomain.com/success.html
<head>
...
// Shoptimiza analytics tag
...
</head>
<body>
....
<script>
// Let's say we've just sold products p1 and p2
	var products = ['p1','p2'];
	sa('track', 'conversion', customerId, orderId, products, signature);
</script>

Where:

customerId is your customer ID
orderId is your order ID
products should be an array of purchased product IDs.
signature sign your conversion request with your shared secret

You can calculate the signature on the server as follows:

// PHP example
$signatureParams = $id_customer."|".$id_order."|p1,p2"
$signature = hash_hmac('sha256', $signatureParams, $shoptimiza_shared_secret);

If you do not have a valid identifier for customerId you can just pass an empty string.

customerId can not be any personally identifiable information PII as considered by the GDPR. You can address any questions regarding this topic to integrations@shoptimiza.com

It does not matter if the conversion is sent more than once, we will count just one.