Get Customization

Overview

Retrieve one customization by its unique identifier.

Caution

This endpoint requires HMAC authentication. See Authentication.

GET https://live.luigisbox.com/v1/recommender/pin/{TRACKER_ID}/scope/{CUSTOMIZATION_ID}

Request parameters

Path parameters

Parameter	Type	Required	Description
TRACKER_ID	string	✓	Your unique tracker identifier.
CUSTOMIZATION_ID	UUID	✓	The unique ID of the customization to retrieve.

Request headers

Header	Value	Description
Content-Type	application/json; charset=utf-8	Required.
Date	HTTP date	Required for HMAC.
Authorization	ApiAuth {TRACKER_ID}:{SIGNATURE}	Required for HMAC.

Example Request

tracker_id="1234-5678"
customization_id="199620b4-df1a-46e8-ab59-9e9ed9af7106"
private_key="your_private_api_key"
host="https://live.luigisbox.com"
path="/v1/recommender/pin/${tracker_id}/scope/${customization_id}"
method="GET"
content_type="application/json; charset=utf-8"
date=$(date -u "+%a, %d %b %Y %H:%M:%S GMT")

string_to_sign="$(printf "${method}\n${content_type}\n${date}\n${path}")"
signature=$(echo -n "${string_to_sign}" | openssl dgst -sha256 -hmac "${private_key}" -binary | base64)

curl -X ${method} "${host}${path}" \
  -H "Content-Type: ${content_type}" \
  -H "Date: ${date}" \
  -H "Authorization: ApiAuth ${tracker_id}:${signature}"

How to Make a Request

1. Build the string to sign from the method, content type, date, and the full resource path including the customization ID.
2. Generate the HMAC SHA-256 digest using your private key.
3. Send the Date, Content-Type, and Authorization headers with the request.

Code Examples

Ruby

require 'faraday'
require 'base64'
require 'openssl'
require 'time'

def generate_luigisbox_digest(private_key, http_method, endpoint_path, date_header, content_type_header)
  data = "#{http_method}\n#{content_type_header}\n#{date_header}\n#{endpoint_path}"
  Base64.strict_encode64(OpenSSL::HMAC.digest('sha256', private_key, data)).strip
end

tracker_id = 'YOUR_TRACKER_ID'
customization_id = '199620b4-df1a-46e8-ab59-9e9ed9af7106'
endpoint_path = "/v1/recommender/pin/#{tracker_id}/scope/#{customization_id}"
date_header = Time.now.utc.strftime("%a, %d %b %Y %H:%M:%S GMT")
content_type = 'application/json; charset=utf-8'
signature = generate_luigisbox_digest('your_private_api_key', 'GET', endpoint_path, date_header, content_type)

response = Faraday.new(url: 'https://live.luigisbox.com').get(endpoint_path) do |req|
  req.headers['Date'] = date_header
  req.headers['Content-Type'] = content_type
  req.headers['Authorization'] = "ApiAuth #{tracker_id}:#{signature}"
end

puts response.body

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

function generateLuigisboxDigest($privateKey, $httpMethod, $endpointPath, $dateHeader, $contentTypeHeader) {
    $data = "{$httpMethod}\n{$contentTypeHeader}\n{$dateHeader}\n{$endpointPath}";
    return trim(base64_encode(hash_hmac('sha256', $data, $privateKey, true)));
}

$trackerId = 'YOUR_TRACKER_ID';
$customizationId = '199620b4-df1a-46e8-ab59-9e9ed9af7106';
$endpointPath = "/v1/recommender/pin/{$trackerId}/scope/{$customizationId}";
$contentType = 'application/json; charset=utf-8';
$date = gmdate('D, d M Y H:i:s') . ' GMT';
$signature = generateLuigisboxDigest('your_private_api_key', 'GET', $endpointPath, $date, $contentType);

$client = new Client();
$response = $client->request('GET', "https://live.luigisbox.com{$endpointPath}", [
    'headers' => [
        'Content-Type' => $contentType,
        'Date' => $date,
        'Authorization' => "ApiAuth {$trackerId}:{$signature}",
    ],
]);

echo $response->getBody();

JavaScript

const axios = require('axios');
const crypto = require('crypto');

function generateLuigisBoxDigest(privateKey, httpMethod, endpointPath, dateHeader, contentTypeHeader) {
  const data = `${httpMethod}\n${contentTypeHeader}\n${dateHeader}\n${endpointPath}`;
  return crypto.createHmac('sha256', privateKey).update(data).digest('base64').trim();
}

const trackerId = 'YOUR_TRACKER_ID';
const customizationId = '199620b4-df1a-46e8-ab59-9e9ed9af7106';
const endpointPath = `/v1/recommender/pin/${trackerId}/scope/${customizationId}`;
const contentType = 'application/json; charset=utf-8';
const dateHeader = new Date().toUTCString();
const signature = generateLuigisBoxDigest('your_private_api_key', 'GET', endpointPath, dateHeader, contentType);

axios({
  method: 'GET',
  url: `https://live.luigisbox.com${endpointPath}`,
  headers: {
    'Content-Type': contentType,
    Date: dateHeader,
    Authorization: `ApiAuth ${trackerId}:${signature}`,
  },
}).then((response) => console.log(response.data));

Response structure

The response contains the full customization object.

Response attributes

Field	Type	Description
id	UUID	Unique customization identifier.
model	string	Recommender model, for example basket.
target_type	string	item, criteria, or all.
target_identity	string	Target identity when target_type is item.
target_criteria	object	Criteria definition when target_type is criteria.
tags	array	Organizational tags.
pin_definitions	array	Pin definitions for the customization.
creator	string	User who created the customization.
created_at	string	Creation timestamp.
available	boolean	Whether the customization is currently active.

Example Response

{
  "id": "199620b4-df1a-46e8-ab59-9e9ed9af7106",
  "created_at": "2025-01-22T08:49:58Z",
  "model": "basket",
  "target_type": "item",
  "target_identity": "/p/123",
  "target_metadata": {
    "title": "Fender Telecaster",
    "image_link": "https://doe.com/123.jpg"
  },
  "pin_definitions": [
    {
      "position": 1,
      "pin_type": "item",
      "pin_identity": "/p/555",
      "active_from": "2025-02-01T00:00:00Z"
    }
  ]
}

Error handling

HTTP Status	Description
200 OK	Success.
401 Unauthorized	Missing or invalid authentication.
404 Not Found	Customization not found.

Example Error

{
  "reason": "Tracker not found",
  "exception_details": {}
}