Marqo Event Tracking API Guide

Overview

The Marqo Event Tracking API allows you to track user interactions on ecommerce websites by sending HTTP requests directly to the Marqo API. Track key events such as searches, clicks, add-to-cart actions, and purchases. These events are collected by Marqo and made available for model training and index optimization.

Features

Direct API Integration: Send tracking data directly via HTTP requests
A/B Testing Support: Include experiment identifiers for testing different approaches
Comprehensive Event Tracking: Track searches, clicks, add-to-cart, and purchases
Flexible Implementation: Integrate from any backend system or client application

⚠️ Critical Implementation Guidelines

Before implementing, please note these important restrictions:

Swatch/Variant Changes: Only log Click and Add to Cart events when product swatches/variants have NOT been changed from the original selection
Filter Applications: Do not send Click or Add to Cart events when filters have been applied to search/collection results
Document ID Matching: Track original docId values from search/collection views and only log downstream ClickEvents and AddToCartEvents when there's a match.
Field Requirements: collectionId must match values used in Marqo's productCollections field, docId must correspond to Marqo's _id field in the Marqo index

See detailed guidelines below for complete implementation instructions.

High Level Implementation

There are a few main steps to implementing Marqo Event Tracking:

Gather your customerID, experimentID, and API key from your Marqo account.
Configure your application to send HTTP POST requests to the Marqo API endpoint.
[Optional] If running A/B experiments, include the appropriate experiment identifiers in your requests.
Implement event tracking for each user interaction you want to monitor (detailed below).

Prerequisites

Reach out to the Marqo team for access to your customerID and experimentID.
Locate your API Key from the Marqo Cloud Console.

API Configuration

Configuration Variables

Gather the following information from your Marqo account:

Parameter	Type	Description
`customerId`	string	Your unique customer identifier from Marqo
`experimentId`	string	Unique identifier for this tracking session (not used for experiment variants)
`apiKey`	string	API key for authentication from Marqo Cloud Console
`customVariant`	string	Optional. Specify experiment variant for A/B testing

API Endpoint

All events should be sent to:

POST https://metrics-client-gateway-7as0xbl6.uc.gateway.dev

A/B Testing with Event Tracking

When running A/B experiments, you can include additional context in your event tracking to analyze the performance of different approaches.

Experiment Tracking Strategy

Assign Users to Variants: Implement your own logic to assign users to different experiment groups
Include Experiment Context: Use the customVariant field to specify which experiment variant the user is experiencing
Track Consistently: Ensure the same user always gets the same variant throughout their session

Example Implementation

curl -X POST "https://metrics-client-gateway-7as0xbl6.uc.gateway.dev" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Origin: https://yourdomain.com" \
  -d '{
    "events": [{
      "eventType": "ClickEvent",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456",
      "customVariant": "variant_a",
      "title": "Running Shoes",
      "docId": "12345",
      "referrerUrl": "https://yourdomain.com/",
      "pageUrl": "https://yourdomain.com/products/running-shoes"
    }]
  }'

Event Tracking API Calls

Track user interactions by sending HTTP POST requests to the Marqo API endpoint with the appropriate event data and authentication headers.

Required Headers

All API calls must include these headers:

Content-Type: application/json
x-api-key: YOUR_API_KEY
Origin: https://yourdomain.com

Event Structure

All events follow this structure with an events array:

{
  "events": [
    {
      "eventType": "...",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456", 
      "customVariant": "variant_a", // Optional: for A/B testing
      // Event-specific data goes here at the top level
      "query": "example search term",
      "docId": "12345",
      "title": "Product Title"
    }
  ]
}

Event Types and Examples

Here are the 5 main event types for tracking user interactions:

Important: All events use a flat structure with event-specific data alongside common fields.

Search Event

Track when a user performs a search.

curl -X POST "https://metrics-client-gateway-7as0xbl6.uc.gateway.dev" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Origin: https://yourdomain.com" \
  -d '{
    "events": [{
      "eventType": "SearchEvent",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456",
      "query": "red sneakers",
      "referrerUrl": "https://yourdomain.com/",
      "pageUrl": "https://yourdomain.com/search?q=red+sneakers"
    }]
  }'

Collection View Event

Track when a user views a collection page.

curl -X POST "https://metrics-client-gateway-7as0xbl6.uc.gateway.dev" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Origin: https://yourdomain.com" \
  -d '{
    "events": [{
      "eventType": "CollectionViewEvent",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456",
      "collectionId": "shoes",
      "referrerUrl": "https://yourdomain.com/",
      "pageUrl": "https://yourdomain.com/collections/shoes"
    }]
  }'

Click Event

Track user clicks (like product views or button clicks).

curl -X POST "https://metrics-client-gateway-7as0xbl6.uc.gateway.dev" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Origin: https://yourdomain.com" \
  -d '{
    "events": [{
      "eventType": "ClickEvent",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456",
      "docId": "12345",
      "title": "Running Shoes Red for Men",
      "referrerUrl": "https://yourdomain.com/search?q=red+sneakers",
      "pageUrl": "https://yourdomain.com/products/running-shoes-red-men"
    }]
  }'

Add to Cart Event

Track when a user adds a product to their cart.

curl -X POST "https://metrics-client-gateway-7as0xbl6.uc.gateway.dev" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Origin: https://yourdomain.com" \
  -d '{
    "events": [{
      "eventType": "AddToCartEvent",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456",
      "docId": "12345",
      "title": "Running Shoes Red for Men",
      "referrerUrl": "https://yourdomain.com/search?q=red+sneakers",
      "pageUrl": "https://yourdomain.com/products/running-shoes-red-men"
    }]
  }'

Purchase Event

Track completed purchases.

curl -X POST "https://metrics-client-gateway-7as0xbl6.uc.gateway.dev" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Origin: https://yourdomain.com" \
  -d '{
    "events": [{
      "eventType": "PurchaseEvent",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456",
      "docId": ["12345", "67890"],
      "quantity": [1, 2],
      "title": ["Running Shoes Red for Men", "Blue Athletic Socks"],
      "price": [76, 15],
      "referrerUrl": "https://yourdomain.com/cart",
      "pageUrl": "https://yourdomain.com/checkout"
    }]
  }'

Important Implementation Guidelines

Swatch and Variant Selection Tracking

CRITICAL: Only log Click Events and Add to Cart Events when the product swatch or variant has NOT been changed from the original selection. This applies to:

Product cards on search results pages: Do not log events if the user changes the swatch/variant on the product card
Product detail pages (PDP): Do not log events if the user changes the swatch/variant on the PDP

Solution: Track Original Document IDs

To implement this correctly:

Capture Original DocIds: When displaying search results or collection views, track the docId values of the originally displayed products
Match Before Logging: Only send Click Events or Add to Cart Events if the current docId matches one of the original docId values from the initial search or collection view
Reset on New Search/Collection: Clear the tracked docId list when the user performs a new search or navigates to a different collection

Filter Application Restrictions

Do not send Click Events or Add to Cart Events when filters have been applied. If a user applies any filter to refine their search or collection view, do not log subsequent click or add-to-cart interactions until they perform a new search or navigate to a new collection without filters.

Parameter Descriptions

Based on the confirmed API structure:

Common Event Fields (Required for All Events)

Parameter	Type	Description	Required
`eventType`	string	Type of event: "SearchEvent", "CollectionViewEvent", "ClickEvent", "AddToCartEvent", "PurchaseEvent"	Yes
`customerId`	string	Your unique customer identifier	Yes
`experimentId`	string	Unique identifier for tracking session	Yes
`userId`	string	Unique identifier for the user	Yes
`sessionId`	string	Unique identifier for the user session	Yes
`customVariant`	string	Experiment variant for A/B testing	No

Search Event Fields

Parameter	Type	Description
`query`	string	Search query entered by user
`referrerUrl`	string	URL of the page that referred the user to this page
`pageUrl`	string	Current page URL where the event occurred

Collection View Event Fields

Parameter	Type	Description
`collectionId`	string	ID of the collection (must match the value used in the `productCollections` field when retrieving from the Marqo collection endpoint)
`referrerUrl`	string	URL of the page that referred the user to this page
`pageUrl`	string	Current page URL where the event occurred

Click Event Fields

Parameter	Type	Description
`docId`	string	Document identifier (must correspond to the `_id` field in Marqo)
`title`	string	Product title
`referrerUrl`	string	URL of the page that referred the user to this page
`pageUrl`	string	Current page URL where the event occurred

Add to Cart Event Fields

Parameter	Type	Description
`docId`	string	Document identifier (must correspond to the `_id` field in Marqo)
`title`	string	Product title
`referrerUrl`	string	URL of the page that referred the user to this page
`pageUrl`	string	Current page URL where the event occurred

Purchase Event Fields

Parameter	Type	Description
`docId`	string or array	Document identifier(s) (must correspond to the `_id` field in Marqo)
`quantity`	number or array	Number of items purchased (array for multiple products)
`title`	string or array	Product title(s) (array for multiple products)
`price`	number or array	Price per item (array for multiple products)
`referrerUrl`	string	URL of the page that referred the user to this page
`pageUrl`	string	Current page URL where the event occurred

Session Management and User Tracking

With the API-based approach, you are responsible for managing user sessions and tracking if needed for your use case.

Implementation Notes

Required Fields: Every event must include eventType, customerId, experimentId, userId, and sessionId
Flat Structure: Event-specific data goes at the top level alongside common fields
Simple Structure: Keep only essential fields as shown in the examples above
Privacy Compliance: Ensure event tracking complies with privacy regulations

Authentication and Security

All API calls to the Marqo tracking service require proper authentication and should follow security best practices.

Authentication Headers

Each API request must include the following headers:

Header	Description	Example
`Content-Type`	Specifies JSON content format	`application/json`
`x-api-key`	API key for authentication	`<api_key>`
`Origin`	Your website domain	`https://yourdomain.com`

Security Best Practices

HTTPS Only: Always use HTTPS when making API calls
API Key Protection: Store API keys securely and never expose them in client-side code
Rate Limiting: Implement appropriate rate limiting to avoid API throttling
Error Handling: Implement retry logic with exponential backoff for failed requests
Data Validation: Validate all data before sending to ensure proper formatting
CORS Considerations: Ensure your domain is authorized for cross-origin requests if calling from browser

Marqo Data Collection Policy

Overview

Marqo is committed to protecting and ensuring the privacy and security of our customers and their site users. We believe in transparency regarding how we collect and use data to improve our services. When you implement Marqo event tracking on your site, we collect limited user interaction data that you choose to send. This data is exclusively used for fine-tuning our base models, optimizing index settings, enhancing search relevance and accuracy, providing better overall search experiences for your users. This data is not sold to third parties and is retained in our system for a default period of 2 years. Marqo has robust mechanisms to delete and remove this data upon request from our customers.

Data Collection Details

Marqo collects various types of data through the event tracking API. The exact data collection scope is subject to the specific implementation chosen by the customer, but typically includes:

User Interaction Events

Search Activity
- Search queries
- Filter selections
- Search refinements
- Results viewed
E-commerce Interactions
- Add-to-cart actions
- Purchase completions
- Product views
- Checkout processes
Site Engagement
- Button clicks
- Page navigation
- Content interaction
- Session duration

Technical Information

Browser type and version
Device information (desktop, mobile, tablet)
Operating system
Date and time of interactions
HTTP information: protocol, version, and response code

Data Security and Compliance

All collected data is processed in compliance with relevant data protection regulations and accessible only to authorized personnel

Data Usage Benefits

The data collected through Marqo event tracking directly contributes to: source- More accurate search results for your users - Personalized search experiences - Improved product recommendations - Enhanced analytics and insights - Continuous improvement of the Marqo platform For additional information or to discuss specific data collection requirements, please contact our team at support@marqo.ai.