Quickstart: Tracking purchases and key conversions with the Events API

Introduction

You’ve learned how to track what users see and click on using the Events API. The next crucial step is to track when they perform a meaningful action, known as a conversion. A conversion is any user action that is important to your business, but the most significant one is a completed purchase.

Tracking purchases provides the strongest possible positive signal to the Luigi’s Box AI models, directly teaching them which products are most valuable and helping to improve search ranking and recommendations for all future users.

What you’ll learn

How to send an “add to cart” conversion event using the Events API.
How to send a transaction event to record a completed purchase using the Events API.
Best practices for tracking conversion events accurately with the Events API.

Who is this guide for

Developers who have already completed the “Quickstart: Send your first search events with the Events API” guide and have a working setup for tracking views and clicks via the API.

Prerequisites

Before you start, please ensure you have the following:

A working analytics setup using the Events API.
Luigi’s Box tracker_id.
The ability to add tracking code to your backend logic that fires when a user adds an item to the cart and completes a purchase.

Step-by-step

All events are sent via an HTTP POST request to https://api.luigisbox.com/.

Step 1: Track the “add to cart” event

Tracking when a user adds an item to their cart is a key “micro-conversion” that signals strong interest. You should send a click event with a descriptive action.type every time this action occurs.

Structure the JSON payload

{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", // A globally unique ID for this event
  "type": "click",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": 6667519810961010000,
  "action": {
    "type": "add-to-cart",                   // Descriptive action type
    "resource_identifier": "SKU_12345"       // The ID of the item added to the cart
  },
  "platform": "backend" // Optional
}

Key fields explained

type: Must be exactly "click" for this type of conversion.
action.type: Use a descriptive name like “add-to-cart”. Anything other than “click” for action.type is considered a conversion.
action.resource_identifier: The unique ID of the product being added to the cart. This must match the ID in your catalog.

Examples

These examples show how to make HTTP POST requests to the Events API.

require 'faraday'
require 'json'
require 'securerandom'

# --- Configuration (ensure these are defined, e.g., from a previous guide/setup) ---
TRACKER_ID = "YOUR_TRACKER_ID"
API_ENDPOINT = "https://api.luigisbox.com/"
CLIENT_ID = 6667519810961010000

# --- Helper Function using Faraday (ensure this is defined) ---
# def send_luigis_box_event(payload) ... end

add_to_cart_payload = {
  id: SecureRandom.uuid,
  type: "click",
  tracker_id: TRACKER_ID,
  client_id: CLIENT_ID,
  action: {
    type: "add-to-cart",
    resource_identifier: "SKU_12345" # ID of item added
  },
  platform: "backend-ruby-faraday"
}

puts "Sending 'Add to Cart' Event..."
send_luigis_box_event(add_to_cart_payload)

<?php
// Make sure to include the Composer autoloader and that helper functions/config are defined
require 'vendor/autoload.php';
use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

// --- Configuration (ensure these are defined) ---
$trackerId = "YOUR_TRACKER_ID";
$apiEndpoint = "https://api.luigisbox.com/";
$clientId = 6667519810961010000;

// --- Helper Functions (ensure guidv4 and sendLuigisBoxEvent are defined) ---
// function guidv4(...) { ... }
// function sendLuigisBoxEvent(...) { ... }

$addToCartPayload = [
    "id" => guidv4(),
    "type" => "click",
    "tracker_id" => $trackerId,
    "client_id" => $clientId,
    "action" => [
        "type" => "add-to-cart",
        "resource_identifier" => "SKU_12345" // ID of item added
    ],
    "platform" => "backend-php-guzzle"
];

echo "Sending 'Add to Cart' Event...\n";
sendLuigisBoxEvent($apiEndpoint, $addToCartPayload);
?>

const axios = require('axios');
const { v4: uuidv4 } = require('uuid');

// --- Configuration (ensure these are defined) ---
const TRACKER_ID = "YOUR_TRACKER_ID";
const API_ENDPOINT = "https://api.luigisbox.com/";
const CLIENT_ID = 6667519810961010000;

// --- Helper Function to Send Event (ensure this is defined) ---
// async function sendLuigisBoxEvent(payload) { ... }

const addToCartPayload = {
  id: uuidv4(),
  type: "click",
  tracker_id: TRACKER_ID,
  client_id: CLIENT_ID,
  action: {
    type: "add-to-cart",
    resource_identifier: "SKU_12345" // ID of item added
  },
  platform: "backend-nodejs"
};

(async () => {
  console.log("Sending 'Add to Cart' Event...");
  await sendLuigisBoxEvent(addToCartPayload);
})();

Step 2: Track the purchase event

This is the final and most important conversion. When a transaction is successfully completed, send a transaction event. This event should contain details about the entire transaction.

Structure the JSON payload

{
  "id": "03dd16c3-4dd5-44c0-87c4-b3a652c06a87", // A new unique ID for this event
  "type": "transaction",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": 6667519810961010000,
  "items": [
    {
      "title": "White shirt, round neck, short sleeves",
      "url": "9339993",              // Unique ID of the product
      "count": 1,                    // Quantity purchased
      "total_price": 19,             // Total price for this line item (quantity * unit_price)
      "was_discounted": false,
      "was_volume_discounted": false
    },
    {
      "title": "Brown overcoat",
      "url": "299299",
      "count": 2,
      "total_price": 268.50,
      "was_discounted": true,
      "was_volume_discounted": false
    }
    // ... all other items in the transaction
  ]
}

Key fields explained

type: Must be exactly "transaction" for this type of conversion.
items: An array containing details for each product in the order.
items.url: The unique ID of the purchased product, matching your catalog.
items.count: The quantity of this specific product purchased.
items.total_price: The total price for this line item (i.e., unit price multiplied by quantity), after any applicable discounts.
items.was_discounted: Boolean indicating if any discount was applied to this item.
items.was_volume_discounted: Boolean indicating if a discount was applied based on quantity.

Examples

# (Assuming send_luigis_box_event and config from previous guide are defined)

purchased_items_details = [
  { title: "White shirt...", url: "9339993", count: 1, total_price: 19, was_discounted: false, was_volume_discounted: false },
  { title: "Brown overcoat", url: "299299", count: 2, total_price: 268.50, was_discounted: true, was_volume_discounted: false }
]

transaction_payload = {
  id: SecureRandom.uuid,
  type: "transaction",
  tracker_id: TRACKER_ID,
  client_id: CLIENT_ID,
  items: purchased_items_details
}

puts "Sending Transaction Event..."
send_luigis_box_event(transaction_payload)

<?php
// (Assuming sendLuigisBoxEvent, guidv4, and config from previous guide are defined)

$purchasedItemsDetails = [
    ["title" => "White shirt...", "url" => "9339993", "count" => 1, "total_price" => 19, "was_discounted" => false, "was_volume_discounted" => false],
    ["title" => "Brown overcoat", "url" => "299299", "count" => 2, "total_price" => 268.50, "was_discounted" => true, "was_volume_discounted" => false]
];

$transactionPayload = [
    "id" => guidv4(),
    "type" => "transaction",
    "tracker_id" => $trackerId,
    "client_id" => $clientId,
    "items" => $purchasedItemsDetails
];

echo "Sending Transaction Event...\n";
sendLuigisBoxEvent($apiEndpoint, $transactionPayload);
?>

// (Assuming sendLuigisBoxEvent, uuidv4, and config from previous guide are defined)

const purchasedItemsDetails = [
  { title: "White shirt...", url: "9339993", count: 1, total_price: 19, was_discounted: false, was_volume_discounted: false },
  { title: "Brown overcoat", url: "299299", count: 2, total_price: 268.50, was_discounted: true, was_volume_discounted: false }
];

const transactionPayload = {
  id: uuidv4(),
  type: "transaction",
  tracker_id: TRACKER_ID,
  client_id: CLIENT_ID,
  items: purchasedItemsDetails
};

(async () => {
  console.log("Sending Transaction Event...");
  await sendLuigisBoxEvent(transactionPayload);
})();

Best practices

Track on confirmation: Fire the transaction event only after payment is successfully confirmed. This prevents tracking abandoned or failed transactions and keeps your data clean.
Include all items: The items array in a transaction event should contain every single item from the order to give the AI a complete picture of what was purchased together.
Verify with the session explorer: After sending a test conversion or transaction, use the Live Session Explorer in the Luigi’s Box application to confirm that the event was received correctly with all its data.
Use descriptive action types: For non-purchase conversions (like “add_to_wishlist”), use clear and consistent names for action.type.

Next steps

Beyond adding to the cart and purchasing, you can track other important conversions that signal user interest:

Analyze performance: Once tracking is in place, you can use the Luigi’s Box Analytics dashboard to see how your search and recommendation features are driving these key conversions.

Was this page helpful?

Thanks.