Shopping Assistant API

Overview

Use the Shopping Assistant API to power a question-and-answer product finder on your own site.

You define the assistant in the Luigi’s Box app. Your integration then calls this endpoint to:

1. get the first question
2. send back the user’s selected answers
3. receive the next question together with the currently matching products

In other words, this endpoint does not just return products. It returns the current state of the guided flow: the next question to show and the product list that matches the answers collected so far.

Luigi’s Box Assistant can learn from user interactions when Luigi’s Box analytics is integrated with your site. For click, add-to-cart, and conversion tracking, see Shopping Assistant analytics.

Note

This endpoint is public and requires no authentication.

Tip

For implementation planning, start with Shopping Assistant implementation flow. For runnable code, use Building a custom shopping assistant. For measurement, see Shopping Assistant analytics.

POST https://live.luigisbox.com/v1/assistant

Request

Send a POST request to the endpoint. Query parameters identify the tracker and assistant. The JSON body carries the dialogue state and runtime overrides.

Query parameters

Parameter	Type	Required	Description
tracker_id	string	✓	Your site identifier within Luigi’s Box. You can find this identifier in every URL in the Luigi’s Box app once you are logged in.
assistant_handle	string	✓	The unique handle of the assistant to use.
user_id	string	Recommended	The unique identifier of the end-user. If it matches the user ID collected in analytics, it can connect assistant requests to the same user or session and support personalization where available.

Request body parameters

Parameter	Type	Description
assistant_version	integer	The version of the assistant to use. This parameter is required. Use -1 for the latest published version, or pass a specific published version when you need deterministic behavior.
steps	array[object]	An array of previous interactions (questions and answers) in the dialogue. Each step contains the question handle and one or more selected option handles. Send an empty array or omit this field for the first request.
next_question_handle	string	The handle of the next question to be presented to the user. If an option returns next_question_handle, pass it in your next request to continue that branch of the flow.
size	integer	The number of product results to return. Default: 10. Maximum: 200.
price_field	string	The product field used for calculating price ranges. Defaults to price_amount. If you want to use a different numeric field, specify it here. If the field does not exist or is not numeric, the request returns 400.
hit_fields	string	A comma-separated list of hit attributes to include in the response, for example title,sku,image_link. This controls fields inside each hit’s attributes object. Top-level hit fields such as url are always returned.
field_overrides	object	An object that replaces fields used by the assistant’s filters and facets with other indexed fields at request time. A typical use case is runtime pricing, for example replacing price_amount with price_amount_7 for a logged-in user. Source and target fields must exist and use compatible types.
sort	string	The sorting criteria for the product results, for example price:asc or price:desc,title:asc. If not provided, the default sorting is applied.
context	object	An object that overrides fields used by search. The fields available for overriding are availability_field, availability_rank_field, freshness_field, boost_field, geo_location_field, margin_field, absolute_margin_field, and discount_field.
f	array[string]	An array of OR filters to apply to the product results (for example category:electronics or price:1|5).
f_must	array[string]	An array of AND filters that must match the product results (for example category:electronics or price:1|5 ).
neg_f	array[string]	An array of OR filters to exclude product results (for example category:electronics or price:1|5).
neg_f_must	array[string]	An array of AND filters to exclude the product results (for example category:electronics or price:1|5).
search_in_variants	boolean	A boolean value indicating whether to search in product variants. If set to true, the search includes variants of products. Defaults to the search setting configured in the app.
non_collapsed_variants	boolean	A boolean value indicating whether to return non-collapsed variants in the results. If set to true, variants are returned as separate items in the results. Works only when search_in_variants is allowed.

Step object fields

Field	Type	Description
question_handle	string	The handle of the question the user answered.
option_handles	array[string]	An array of selected option handles for that question.

Request headers

Header	Value	Required	Description
Content-Type	application/json	✓	The content type of the request body.
Accept-Encoding	gzip, deflate	Recommended	The accepted response compression formats.

Example Request

curl -X POST "https://live.luigisbox.com/v1/assistant?tracker_id=1234-5678&assistant_handle=shoe_finder&user_id=123456" \
  -H "Content-Type: application/json" \
  -H "Accept-Encoding: gzip, deflate" \
  -d '{
    "assistant_version": 1,
    "steps": [
      {
        "question_handle": "budget",
        "option_handles": ["budget-low"]
      }
    ],
    "hit_fields": "title,price_amount,image_link",
    "field_overrides": {
      "price_amount": "price_amount_7"
    }
  }'

How to make a request

The endpoint is stateful from your application’s perspective. Your frontend or backend keeps track of answered steps and resends them on every request.

1. Start the flow with an empty steps array.
2. Render the returned question and hits.
3. Append the selected answer to steps.
4. If the selected option included next_question_handle, send that exact value in the next request.
5. Call the endpoint again with the updated state.
6. Stop when question becomes null.

Code Examples

Ruby

require 'faraday'
require 'json'

connection = Faraday.new(url: 'https://live.luigisbox.com')

response = connection.post('/v1/assistant') do |req|
  req.params['tracker_id'] = '1234-5678'
  req.params['assistant_handle'] = 'shoe_finder'
  req.params['user_id'] = '123456'
  req.headers['Content-Type'] = 'application/json'
  req.body = {
    assistant_version: 1,
    steps: [
      {
        question_handle: 'budget',
        option_handles: ['budget-low']
      }
    ],
    hit_fields: 'title,price_amount,image_link',
    field_overrides: {
      price_amount: 'price_amount_7'
    }
  }.to_json
end

puts JSON.pretty_generate(JSON.parse(response.body))

PHP

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

use GuzzleHttp\Client;

$client = new Client();

$response = $client->post('https://live.luigisbox.com/v1/assistant', [
    'query' => [
        'tracker_id' => '1234-5678',
        'assistant_handle' => 'shoe_finder',
        'user_id' => '123456',
    ],
    'json' => [
        'assistant_version' => 1,
        'steps' => [
            [
                'question_handle' => 'budget',
                'option_handles' => ['budget-low'],
            ],
        ],
        'hit_fields' => 'title,price_amount,image_link',
        'field_overrides' => [
            'price_amount' => 'price_amount_7',
        ],
    ],
]);

echo $response->getBody();

JavaScript

import axios from "axios";

const trackerId = "1234-5678";
const assistantHandle = "shoe_finder";
const userId = "123456";
const endpoint = "https://live.luigisbox.com/v1/assistant";

let steps = [];

async function fetchAssistant(nextQuestionHandle = undefined) {
  const response = await axios.post(
    endpoint,
    {
      assistant_version: 1,
      steps,
      next_question_handle: nextQuestionHandle,
      hit_fields: "title,price_amount,image_link",
      field_overrides: {
        price_amount: "price_amount_7",
      },
    },
    {
      params: {
        tracker_id: trackerId,
        assistant_handle: assistantHandle,
        user_id: userId,
      },
      headers: {
        "Accept-Encoding": "gzip, deflate",
      },
    },
  );

  return response.data;
}

function registerAnswer(questionHandle, optionHandle) {
  steps.push({
    question_handle: questionHandle,
    option_handles: [optionHandle],
  });
}

HTTP response

The endpoint returns the current result set and, when applicable, the next question in the assistant flow.

Top-level fields

Field	Description
assistant_handle	The handle of the assistant used for this response.
tracker_id	The Luigi’s Box tracker identifier.
hits	An array of hit objects matching the current dialogue state.
important_attributes	An array of attribute names Luigi’s Box considers useful to highlight in the hit list.
avatar_image_link	The URL of the assistant avatar image, if available.
intro_html	The introductory HTML for the assistant flow, if available.
question	The next question to display, or null when the flow is finished.
steps	An echo of the current step state, when applicable.

Hit fields

Field	Description
hits[].url	The URL of the matched product.
hits[].type	The type of the returned hit.
hits[].attributes	An object containing the product attributes returned in the response. The exact keys depend on your catalog and hit_fields.
hits[].updated_at	The timestamp of the last hit update, if available.

Question fields

Field	Description
question.question_handle	The unique handle of the question.
question.title_html	The HTML-formatted title of the question.
question.description_html	The HTML-formatted description of the question, if available.
question.image_link	The URL of the question image, if available.
question.type	The type of the question: single_choice or multi_choice.
question.options	An array of options available for the next answer.

Option fields

Field	Description
option_handle	The unique handle of the option.
title_html	The HTML-formatted title of the option.
description_html	The HTML-formatted description of the option, if available.
parent_question_handle	The handle of the parent question, if available.
next_question_handle	The handle of the next question, if fixed by the assistant definition.
image_link	The URL of the option image, if available.
color_code	The color swatch value of the option, if available.
hits_count	The number of products matching the option.
price_range	The computed price range for the products behind that option.

Example Response

{
  "assistant_handle": "shoe_finder",
  "tracker_id": "1234-5678",
  "hits": [
    {
      "url": "/products/running-shoe-1",
      "type": "product",
      "updated_at": "2026-04-01T12:00:00Z",
      "attributes": {
        "title": "Trail Runner",
        "price_amount": 89,
        "image_link": "https://example.com/images/trail-runner.jpg"
      }
    }
  ],
  "important_attributes": ["brand", "color"],
  "avatar_image_link": "",
  "intro_html": "",
  "question": {
    "question_handle": "color",
    "title_html": "Pick a color",
    "description_html": "Choose the one you are most likely to wear.",
    "image_link": null,
    "type": "single_choice",
    "options": [
      {
        "option_handle": "color-blue",
        "title_html": "Blue",
        "description_html": "Classic and versatile.",
        "parent_question_handle": "color",
        "next_question_handle": null,
        "image_link": "https://example.com/blue.jpg",
        "hits_count": 12,
        "price_range": "69.0 - 119.0"
      }
    ]
  },
  "steps": []
}

Errors

The API uses standard HTTP status codes. Note that the format of the error response body can vary depending on the type of error.

Parse the status code first, then inspect the response body when one is present.

Status	Meaning
400 Bad Request	An invalid request. This includes malformed input, incorrect data types, wrong HTTP method, or assistant lookup failures.
404 Not Found	A request to an endpoint path that does not exist. Assistant lookup failures are returned as 400, not 404.
500 Internal Server Error	A temporary internal error. Retry with backoff, and log the Request-Id if the response includes one.

Note

A lookup failure can still return 400 Bad Request. That happens when the request reaches the correct endpoint, but the supplied tracker_id, assistant_handle, or assistant_version cannot be resolved to an assistant.

Error responses

400 Bad Request

{
  "type": "malformed_input",
  "reason": "incorrect parameters provided",
  "caused_by": {
    "assistant_version": ["must be an integer"]
  }
}

404 Not Found

Not Found
Request-Id: <request-id>