Navigation

Update Customization

Update an existing customization by its unique identifier.

Overview

Important This endpoint requires HMAC authentication.

Update an existing customization by its unique identifier. This endpoint replaces the entire configuration of the customization.

Authentication

This endpoint requires HMAC authentication. You must include the Date and Authorization headers. See Authentication for details.

PUT https://live.luigisbox.tech/v1/recommender/pin/{TRACKER_ID}/scope/{CUSTOMIZATION_ID}

Request Parameters

To update a customization, send a PUT request to the endpoint with the tracker_id and scope_id (customization ID) in the path, and the configuration in the body.

Path Parameters

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

Request Headers

Header Value Description
Content-Type application/json Required.
Date HTTP Date Required for HMAC.
Authorization Signature Required for HMAC.

Request Body Attributes

The request body follows the same structure as the Create Customization endpoint.

Parameter Type Required Description
model String ✓ The recommender model.
target_type String ✓ Scope type (item, criteria, all).
target_identity String Item ID (if target_type is item).
target_criteria Object Criteria Object (if target_type is criteria).
tags Array Tags for the customization.
pin_definitions Array ✓ LList of Pin Objects to be set.
widget_id String Widget ID (in pin objects).
is_bundle_pin Boolean Bundle pin flag (in pin objects).
active_from Date-time Start time (in pin objects).
active_to Date-time End time (in pin objects).

Example Request

tracker_id="1234-5678"
customization_id="199620b4-df1a-46e8-ab59-9e9ed9af7106"
private_key="your_private_api_key"
host="https://live.luigisbox.tech"
path="/v1/recommender/pin/${tracker_id}/scope/${customization_id}"
method="PUT"
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}" \
     -d '{
       "model": "basket",
       "target_type": "item",
       "target_identity": "/p/123",
       "pin_definitions": [
         {
           "position": 1,
           "pin_type": "item",
           "pin_identity": "/p/555",
           "active_from": "2025-02-01T00:00:00Z"
         }
       ]
     }'

How to make a request

All requests to this endpoint must be authenticated using HMAC SHA-256. The examples on the right demonstrate the implementation in various languages, but the core logic follows these steps:

1. Construct the String to Sign

Create a string using the following components, separated by newlines (\n):

  1. HTTP Method: PUT
  2. Content-Type: application/json; charset=utf-8
  3. Date: The current timestamp in RFC 1123 format (e.g., Mon, 20 Jan 2025 12:00:00 GMT).
  4. Request Path: The full resource path including the ID.

2. Generate the HMAC Signature

  1. Create an HMAC SHA-256 hash of the string above using your Private API Key.
  2. Encode the result in Base64 and trim whitespace.

3. Send the Headers

Include Date, Content-Type, and Authorization: ApiAuth {TRACKER_ID}:{SIGNATURE} in your request..

Example Code

require 'faraday'
require 'base64'
require 'openssl'
require 'json'
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}"
  hash = OpenSSL::HMAC.digest('sha256', private_key, data)
  Base64.strict_encode64(hash).strip
end



tracker_id = 'YOUR_TRACKER_ID'
customization_id = '199620b4-df1a-46e8-ab59-9e9ed9af7106'
private_key = 'your_private_api_key'
host = 'https://live.luigisbox.tech'
endpoint_path = "/v1/recommender/pin/#{tracker_id}/scope/#{customization_id}"



customization_data = {
  "model": "basket",
  "target_type": "item",
  "target_identity": "/p/123",
  "pin_definitions": [
    {
      "position": 1,
      "pin_type": "item",
      "pin_identity": "/p/555"
    }
  ]
}



conn = Faraday.new(url: host)



http_method = 'PUT'
content_type = 'application/json; charset=utf-8'
date_header = Time.now.utc.strftime("%a, %d %b %Y %H:%M:%S GMT")



signature = generate_luigisbox_digest(private_key, http_method, endpoint_path, date_header, content_type)
authorization_header = "ApiAuth #{tracker_id}:#{signature}"



response = conn.put(endpoint_path) do |req|
  req.headers['Date'] = date_header
  req.headers['Content-Type'] = content_type
  req.headers['Authorization'] = authorization_header
  req.body = customization_data.to_json
end



puts response.body

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


use GuzzleHttp\Client;



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



$TRACKER_ID       = "YOUR_TRACKER_ID";
$CUSTOMIZATION_ID = "199620b4-df1a-46e8-ab59-9e9ed9af7106";
$YOUR_PRIVATE_KEY = "your_private_api_key";
$LUIGISBOX_HOST   = 'https://live.luigisbox.tech';
$ENDPOINT_PATH    = "/v1/recommender/pin/{$TRACKER_ID}/scope/{$CUSTOMIZATION_ID}";



$customization_data = [
    "model" => "basket",
    "target_type" => "item",
    "target_identity" => "/p/123",
    "pin_definitions" => []
];



$http_method  = 'PUT';
$content_type = 'application/json; charset=utf-8';
$current_date = gmdate('D, d M Y H:i:s') . ' GMT';



$signature = generateLuigisboxDigest($YOUR_PRIVATE_KEY, $http_method, $ENDPOINT_PATH, $current_date, $content_type);
$authorization_header = "ApiAuth {$TRACKER_ID}:{$signature}";



$client = new GuzzleHttp\Client();
$response = $client->request($http_method, "{$LUIGISBOX_HOST}{$ENDPOINT_PATH}", [
        'headers' => [
            'Content-Type'  => $content_type,
            'Date'          => $current_date,
            'Authorization' => $authorization_header,
        ],
        'json' => $customization_data
    ]);



echo $response->getBody();
?>

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


function generateLuigisBoxDigest(privateKey, httpMethod, endpointPath, dateHeader, contentTypeHeader) {
  const data = </span><span class="p">${</span><span class="nx">httpMethod</span><span class="p">}</span><span class="s2">\n</span><span class="p">${</span><span class="nx">contentTypeHeader</span><span class="p">}</span><span class="s2">\n</span><span class="p">${</span><span class="nx">dateHeader</span><span class="p">}</span><span class="s2">\n</span><span class="p">${</span><span class="nx">endpointPath</span><span class="p">}</span><span class="s2">;
  const hmac = crypto.createHmac('sha256', privateKey);
  hmac.update(data);
  return hmac.digest('base64').trim();
}



const TRACKER_ID = "YOUR_TRACKER_ID";
const CUSTOMIZATION_ID = "199620b4-df1a-46e8-ab59-9e9ed9af7106";
const YOUR_PRIVATE_KEY = "your_private_api_key";
const LUIGISBOX_HOST = 'https://live.luigisbox.tech';
const ENDPOINT_PATH = /v1/recommender/pin/</span><span class="p">${</span><span class="nx">TRACKER_ID</span><span class="p">}</span><span class="s2">/scope/</span><span class="p">${</span><span class="nx">CUSTOMIZATION_ID</span><span class="p">}</span><span class="s2">;



const customizationData = {
  model: "basket",
  target_type: "item",
  target_identity: "/p/123",
  pin_definitions: []
};



const httpMethod = 'PUT';
const contentType = 'application/json; charset=utf-8';
const dateHeader = new Date().toUTCString();



const signature = generateLuigisBoxDigest(YOUR_PRIVATE_KEY, httpMethod, ENDPOINT_PATH, dateHeader, contentType);
const authorizationHeader = ApiAuth </span><span class="p">${</span><span class="nx">TRACKER_ID</span><span class="p">}</span><span class="s2">:</span><span class="p">${</span><span class="nx">signature</span><span class="p">}</span><span class="s2">;



axios({
  method: httpMethod,
  url: </span><span class="p">${</span><span class="nx">LUIGISBOX_HOST</span><span class="p">}${</span><span class="nx">ENDPOINT_PATH</span><span class="p">}</span><span class="s2">,
  headers: {
    'Content-Type': contentType,
    'Date': dateHeader,
    'Authorization': authorizationHeader
  },
  data: customizationData
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Response Structure

The server returns a 204 No Content status code upon successful update.

The Response Object

HTTP/1.1 204 No Content

Error Handling

HTTP Status Description
204 No Content Customization updated successfully.
400 Bad Request Invalid configuration provided.
401 Unauthorized Missing or invalid authentication.
404 Not Found The customization ID was not found.
422 Unprocessable Entity Invalid pin definition provided.

Error Responses

{
  "reason": "Invalid pin definition provided",
  "exception_details": {
    "pin_definitions": ["Missing required field: position"],
    "target_type": ["Must be one of: item, criteria, all"]
  }
}