---
title: Luigi's Box Magento 2 Integration Guide
description: Complete guide to integrating Luigi's Box with Magento 2, including installation, activation, and tracking script setup.
slug: platform-integrations/magento2/integration
docKind: integration
hub: platform-integrations
---

:::note
**Guide Goal (TL;DR):** This guide's sole purpose is to help you connect and **synchronize your Magento 2 product catalog** with Luigi's Box. To integrate the individual services, please go to: [Search](/search/), [Autocomplete](/autocomplete/), [Product Listing](/product-listing/), [Recommendations](/recommendations/), and [Analytics](/analytics/).
:::

## Overview

This guide walks you through integrating Luigi's Box with your Magento 2 store. The integration enables:

- **Search** - AI-powered product search with typo tolerance and synonyms
- **Product Recommendations** - Personalized product suggestions
- **Analytics** - Insights into customer search behavior
- **Automatic Data Sync** - Your catalog stays up-to-date with Luigi's Box

**Time to Complete:** 15-30 minutes
**Prerequisites:** Magento 2.3.1+, PHP 7.4+, Admin access, Store accessible on the internet

<details>
<summary><strong>⚡️ Expert Quickstart (TL;DR)</strong> — <em>Click to expand</em></summary>
<div style="padding: 10px 0;">

<p><strong>1. Install &amp; Enable:</strong></p>

```shell
composer require luigisbox/magento2-integration
php bin/magento setup:upgrade && \
php bin/magento setup:di:compile && \
php bin/magento setup:static-content:deploy -f && \
php bin/magento cache:flush
```

<p><strong>2. Activate:</strong></p>
<ul>
<li>In Magento Admin, go to <strong>System → Extensions → Integrations</strong></li>
<li>Find <strong>LuigisboxIntegration</strong> and click <strong>Activate</strong></li>
<li>Click <strong>Allow</strong> and follow the popup to log in or create your account</li>
</ul>

<p><strong>3. Common Gotchas:</strong></p>

<ul>
  <li><strong>Store Not Public:</strong> Activation will fail if your store is not on the internet. <a href="#phase-2-network-and-security-prerequisites-check-1-store-must-be-publicly-accessible">Test public access</a>.</li>
    <li><strong>Cloudflare:</strong> Regular <strong>Bot Fight Mode</strong> must be disabled. <strong>Super Bot Fight Mode</strong> requires a <a href="#phase-2-network-and-security-prerequisites-check-2-cloudflare-configuration">skip rule</a>.</li>
    <li><strong>Script Not Injected:</strong> If the script doesn't appear in your <code>&lt;head&gt;</code>, <a href="#phase-3-activation-tracking-script-installation-manual-script-injection-fallback">add it manually</a> via <strong>Content → Configuration → HTML Head</strong>.</li>
  </ul>

</div>
</details>

## Phase 1: Installation

**Step 1: Install via Composer**

```shell
  composer require luigisbox/magento2-integration
```


**Step 2: Enable the Module**

Run the following commands in sequence:

```shell
# Run database and schema upgrades
php bin/magento setup:upgrade

# Compile dependency injection configuration
php bin/magento setup:di:compile

# Deploy static content (CSS, JS, images)
php bin/magento setup:static-content:deploy -f

# Clear all caches
php bin/magento cache:flush
```

**Step 3: Verify Installation**

```shell
php bin/magento module:status Luigisbox_Integration
```

Expected output: `Module is enabled`

**In Magento Admin:**

1. Go to **System → Extensions → Integrations**
2. Look for "LuigisboxIntegration" in the list
3. Status should show `"Inactive"` (will activate in Phase 3)

## Phase 2: Network and security

### Prerequisites check

Before activating the integration, ensure your Magento store meets these requirements:

#### Store must be publicly accessible

**Critical:** Luigi's Box needs to access your store's API from the internet.

**Will NOT work:**

- Localhost or local development environments
- Staging servers behind VPN or firewall
- Stores with IP restrictions blocking external access

**Will work:**

- Production stores with public URLs
- Staging servers accessible from the internet

**Test external access:**

From a different network (mobile phone, external server):

```shell
curl -I https://your-store.com/
```

**Expected:** HTTP 200 or 405 response (not timeout or connection refused)

#### Cloudflare configuration

If your store uses **Cloudflare**, you need to configure bot protection settings:

:::danger
Having **Bot Fight Mode** enabled will make communication with Luigi's Box servers impossible. The integration will not work with Bot Fight Mode active.
:::

**If using Super Bot Fight Mode:**

You can create a skip rule to allow Luigi's Box traffic:

1. Log into Cloudflare dashboard
2. Go to **Security → Security Rules**
3. Click **Create rule**
4. Configure the rule:
   - **Rule name:** Allow Luigi's Box
   - **Expression:**
     `(ip.src in {3.126.67.184 3.78.191.91 35.157.250.137 63.177.144.47 52.57.232.136 82.119.103.110} and http.user_agent eq "LuigisBox")`
   - **Choose action:** Skip
   - **WAF components to skip:**
     - All remaining custom rules
     - All rate limiting rules
     - All managed rules
     - All Super Bot Fight Mode rules
   - **More components to skip:**
     - User agent blocking
     - Rate limiting rules
     - Managed rules
   - **Rule placement:** First
5. Click **Save**

This allows Luigi's Box to access your store's API endpoints while keeping bot protection active for
other traffic.

#### HTTP Basic Authentication (if applicable)

If your store uses HTTP Basic Authentication (password protection), you need to allow Luigi's Box to bypass it.

**Configure Nginx to bypass basic auth:**

The configuration has two parts, add them to your Nginx config file (typically `/etc/nginx/sites-available/your-site`):

**Part 1: Add OUTSIDE the `server` block (at the top of your config file):**

```nginx
# Luigi's Box IP whitelist
geo $luigisbox_ip {
    default 0;
    3.126.67.184 1;
    3.78.191.91 1;
    35.157.250.137 1;
    63.177.144.47 1;
    52.57.232.136 1;
    82.119.103.110 1;
}

# Check for Luigi's Box User-Agent
map $http_user_agent $luigisbox_ua {
    default 0;
    "LuigisBox" 1;
}

# Bypass auth only if BOTH IP AND User-Agent match
map "$luigisbox_ip:$luigisbox_ua" $is_luigisbox {
    default 0;
    "1:1" 1;  # Both IP and User-Agent match = bypass auth
}
```

**Part 2: Add INSIDE your `server` block:**

```nginx
# Allow access if: Luigi's Box (IP+UA) OR valid auth credentials
satisfy any;

# Conditionally disable auth for Luigi's Box
set $auth_basic_realm "Restricted Access";
if ($is_luigisbox = 1) {
    set $auth_basic_realm off;
}

auth_basic $auth_basic_realm;
auth_basic_user_file /path/to/.htpasswd;  # Replace with your .htpasswd path
```

**Test and reload Nginx:**

```shell
sudo nginx -t
sudo systemctl reload nginx
```

:::note
**Security**: This configuration requires **BOTH** a matching IP address **AND** the "LuigisBox" User-Agent. This prevents unauthorized access, as an attacker cannot spoof IP addresses (only User-Agent headers). The `satisfy any` directive allows Luigi's Box to bypass auth while keeping existing auth mechanisms working for all other traffic.
:::

### Security information

#### OAuth 1.0a authentication

The integration uses OAuth 1.0a for secure API access:

- **No passwords stored** - Token-based authentication only
- **Encrypted communication** - All API calls over HTTPS
- **Read-only access** - Extension cannot modify products or orders
- **Revocable tokens** - Can disable integration anytime

#### What Luigi's Box can access

**Allowed Resources:**

- Product catalog (SKU, name, description, price, images)
- Categories and category structure
- Inventory levels and stock status
- Product attributes (color, size, brand, custom attributes, etc.)
- Store configuration (currency, timezone, URL, locale)
- Parent-child product relationships (configurable, grouped, bundle products)
- Multi-source inventory data (warehouse locations and quantities)

**NOT Allowed:**

- Customer personal information
- Order history and purchase data
- Payment information
- Admin user accounts
- System passwords or keys

## Phase 3: Activation

### Before you begin

**Important Prerequisites:**

- Extension is installed (Phase 1 complete)
- Store is accessible from the internet (Phase 2 complete)
- You have Magento admin credentials
- Store has at least a few test products (recommended)

**Estimated Time:** 5-10 minutes

### Step-by-step activation

#### Step 1: Access integration settings

1. Log into **Magento Admin Panel**
2. Navigate to **System → Extensions → Integrations**
3. Find **LuigisboxIntegration** in the list
4. Click **Activate** button

![Integration List](/images/platforms/magento_integration.png)

#### Step 2: Confirm activation

A menu appears displaying the API permissions needed.

1. Click **Allow** to proceed
2. Magento generates OAuth credentials automatically
3. Integration status changes to **Active**

**Behind the Scenes:**

- Magento creates OAuth consumer and access token
- Stores credentials in `oauth_consumer` and `oauth_token` database tables
- Integration is now ready to accept API requests

#### Step 3: Authorize with Luigi's Box

After clicking **Allow** in Magento, a **popup window** opens from Luigi's Box.

**In the Luigi's Box popup:**

1. You'll be prompted to either create a new account or log in with existing credentials
2. Follow the on-screen instructions to complete authentication
3. After successful login or account creation, you'll be redirected to the Luigi's Box Web Application

#### Step 4: Get your tracking script

Once in the Luigi's Box dashboard:

1. You'll be presented with your **tracking script**
2. The script will look like: `<script src="https://scripts.luigisbox.tech/LBX-XXXXX.js"></script>`
3. Note your tracker ID (the `LBX-XXXXX` part) for reference

The extension will attempt to inject this script automatically (see "Tracking Script Installation" section below).

#### Step 5: Verify integration status

**In Magento Admin:**

1. Go to **System → Extensions → Integrations**
2. **LuigisboxIntegration** should show:
   - Status: **Active**
   - Consumer Key: Generated (long alphanumeric string)

### Tracking script installation

After successful activation, Luigi's Box attempts to automatically inject its tracking script into your store.

#### What is the tracking script?

The tracking script enables:

- **Search behavior tracking** - What customers search for
- **Product view tracking** - Which products are viewed
- **Click-through tracking** - What search results are clicked
- **Conversion tracking** - Which searches lead to purchases

**Example script:**

```html
<script src="https://scripts.luigisbox.tech/LBX-XXXXX.js"></script>
```

#### Automatic injection (default)

**How It Works:**

Luigi's Box communicates with the Magento to automatically inject the tracking script into your store's `<head>` element on all pages.

**Success Verification:**

1. Open your store homepage in a browser
2. View page source (right-click → View Page Source)
3. Search for "luigisbox" or "LBX-"
4. You should find: `<script src="https://scripts.luigisbox.tech/LBX-XXXXX.js"></script>`

**If Script Appears:** Automatic injection succeeded! Skip to "Next Steps"

#### Manual script injection (fallback)

**When is this needed?**

Automatic injection may fail if:

- Store uses custom theme that doesn't include configuration-based scripts
- Cache isn't cleared after activation
- Store configuration has been customized or overridden

**Symptoms:**

- Script doesn't appear in page source after 10-15 minutes

**Manual installation steps:**

**Via Magento admin**

1. In Magento Admin, go to **Content → Configuration**
2. Click **Edit** for your store view
3. Expand **HTML Head** section
4. In **Scripts and Style Sheets** field, add:
   ```html
   <script src="https://scripts.luigisbox.tech/LBX-XXXXX.js"></script>
   ```
   (Replace `LBX-XXXXX` with your actual Luigi's Box tracker ID from the dashboard)
5. Click **Save Configuration**
6. Clear cache: `php bin/magento cache:flush`

**Verify manual installation:**

1. Open store homepage in **incognito/private window** (bypass cache)
2. View page source
3. Search for "luigisbox"
4. Script should appear in `<head>` section

## Verification and testing

### Verify integration is active

Check that the integration is working correctly:

**In Magento Admin:**

1. Go to **System → Extensions → Integrations**
2. **LuigisboxIntegration** should show Status: **Active**

**In Luigi's Box Dashboard:**

1. Go to **Catalog Browser** section
2. Check product count (should be > 0 after initial sync completes)

### Verify tracking script

1. Open your store homepage in a browser
2. View page source (right-click → View Page Source)
3. Search for "luigisbox" or "LBX-"
4. You should find: `<script src="https://scripts.luigisbox.tech/LBX-XXXXX.js"></script>`

If script doesn't appear, see "Manual Script Injection" section in Phase 3.

### Initial sync

Initial sync begins automatically after activation.

**For detailed sync monitoring, see:** [Magento 2 Data Synchronization Guide](/platform-integrations/magento2/data-sync/)

---

## Next steps

### Immediate (post-integration)

1. **Verify tracking script** is installed (see "Tracking Script Installation")
2. **Wait for initial sync** to complete (5-60 minutes typically)
4. **Review Luigi's Box dashboard** for product data

### Configure your features

Once your catalog is synced, you can implement Luigi's Box features on your storefront.

- Implement [Search](/search/): Activate and configure your new search bar.
- Implement [Recommendations](/recommendations/): Add personalized "cross-sell" and "upsell" carousels to your product and cart pages.
- Implement [Product Listings](/product-listing/): Power your category pages with Luigi's Box for smart filtering and faceting.


### Ongoing maintenance

1. **Monitor data sync** (see [Data Synchronization Guide](/platform-integrations/magento2/data-sync/))
2. **Review search analytics** weekly
3. **Optimize search configuration** based on customer behavior
4. **Update extension** when new versions are released

## Additional resources

- [Data Synchronization Guide](/platform-integrations/magento2/data-sync/)

## Glossary

### Key terms

**Integration**
Connection between Magento and Luigi's Box that enables data synchronization and search functionality.

**OAuth 1.0a**
Industry-standard authentication protocol for secure API access without sharing passwords.

**Access Token**
Secret key that allows Luigi's Box to access your store's API.

**Tracking Script**
JavaScript code that tracks customer search behavior and enables Luigi's Box features.

**Sync / Synchronization**
Process of copying product data from Magento to Luigi's Box servers.