Quickstart: Tracking purchases & 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.
Your Luigi's Box tracker_id can be found in your Luigi's Box application in "General settings" > "Integration settings".
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/](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
<?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 atransaction
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: