Luigi's Box Magento2 Data Synchronization Guide

Overview

Luigi's Box automatically synchronizes your Magento product catalog to power search, recommendations, and analytics. This guide explains what data is synced, how synchronization works, and what to expect.

What Data is Synchronized

Product Information

Luigi's Box syncs comprehensive product data from your Magento store:

Product Types Supported

• Simple products - Standard standalone products
• Configurable products - Products with variants (size, color, etc.)
• Grouped products - Multiple products sold together
• Bundle products - Customizable product bundles
• Virtual products - Non-physical products (services, subscriptions)
• Downloadable products - Digital downloads

Multi-Store & Multi-Warehouse

• Multiple store views - Sync different catalogs per store/language
• Multi-source inventory - Track stock across multiple warehouses
• Regional availability - Show products available in specific locations

How Synchronization Works

1. Initial Full Sync

When: Immediately after activating the integration

What Happens:

1. Luigi's Box connects to your store via secure API
2. Retrieves all enabled and visible products
3. Downloads product details via GraphQL queries
4. Builds searchable index in Luigi's Box system

2. Ongoing Updates (Automatic Sync)

Frequency: Automatic, approximately every 3 hours (8 times per day).

What Happens:

• Luigi's Box periodically checks for changes
• Detects new, updated, or deleted products
• Updates only changed items (not full re-sync)
• Changes typically appear in search within one 3-hour cycle.

Changes Detected:

Luigi's Box compares your current catalog with the previous sync to identify:

• New products added since last sync
• Product information updates (name, description, attributes)
• Price or inventory changes
• Visibility changes (enabled/disabled, search visibility)
• Deleted products

Synchronization Methods

GraphQL API (Primary Method)

Luigi's Box uses Magento's GraphQL API for efficient data retrieval.

Advantages:

• Retrieves only requested data (no overhead)
• Single request for complex product structures
• Handles configurable products elegantly
• Built-in pagination for large catalogs
• Fast and efficient

Custom REST Endpoints

Luigi's Box extension provides specialized endpoints for specific data needs:

1. Script Injection Endpoint

Purpose: Automatically adds tracking script to your store
Endpoint: /rest/V1/insert-script
Used During: Initial activation

2. Parent-Child Relationships

Purpose: Links product variants to parent products
Endpoint: /rest/V1/parent-products-skus
Used For: Configurable, grouped, and bundle products

Authentication & Security

OAuth 1.0a Authentication

All data synchronization uses industry-standard OAuth authentication:

• Secure - No passwords stored or transmitted
• Encrypted - All communication over HTTPS
• Token-based - Unique access token per Magento installation
• Revocable - Can disable access anytime from System → Integrations

What Luigi's Box Can Access

Allowed:

• Product catalog (SKU, name, description, price, images)
• Categories and category structure
• Inventory levels and stock status
• Product attributes (color, size, brand, etc.)
• Store configuration (currency, timezone, URL)

NOT Allowed:

• Customer personal information (names, emails, addresses)
• Order history and purchase data
• Payment information
• Admin user accounts
• System passwords or keys

Minimum Permissions Model

Luigi's Box requests only what's needed:

• No access to customer data
• No access to financial information
• No access to sensitive settings
• Read-only product catalog access

Common Sync Scenarios

Scenario 1: Adding New Products

Your Action:

1. Add 10 new products in Magento admin
2. Set status to "Enabled"
3. Set visibility to "Catalog, Search"
4. Save products

What Happens:

• Luigi's Box detects new products on next scheduled sync
• Sync process automatically downloads new product data
• New products appear in search results
• Analytics begin tracking views and interactions

Scenario 2: Price Updates

Your Action:

1. Update prices for 50 products
2. Apply special prices (discounts)
3. Save changes

What Happens:

• Price changes detected on next sync cycle
• Only modified products re-synced (fast)
• Search results show updated prices
• Price filters update automatically

Scenario 3: Out of Stock Products

Your Action:

1. Product inventory drops to 0
2. Stock status changes to "Out of Stock"

What Happens:

• Inventory change detected on next sync cycle
• Luigi's Box updates product availability
• Product hidden from search (configurable)
• You can enable "notify when back in stock"

Configuration: Control whether out-of-stock products appear in search via Luigi's Box dashboard

Scenario 4: Bulk Import

Your Action:

1. Import 1,000 products via CSV
2. All products enabled and visible

What Happens:

• Next scheduled sync detects 1,000 new products
• May take 10-30 minutes to sync all
• Large imports may slow down sync temporarily

Scenario 5: Deleting Products

Your Action:

1. Delete 5 discontinued products
2. Confirm deletion

What Happens:

• Deletion detected on next sync cycle
• Products removed from Luigi's Box index
• Search results no longer show deleted items

Verifying & Troubleshooting Synchronization

This is the logical flow to follow if you suspect your catalog is not syncing correctly.

Issue 1: Products Are Missing or Not Syncing

This is the most common issue, often caused by configuration settings or not waiting long enough for the automatic sync.

Solution:

1. Wait for the 3-Hour Sync Cycle: The most common "fix" is patience. The sync runs automatically every 3 hours. If you just added a new product, wait for this cycle to complete before troubleshooting.
2. Check Magento Product Configuration: In the Magento Admin, check for a missing product:
   • Is Status set to "Enabled"?
   • Is Visibility set to "Catalog, Search"?
   • Is Integration active? Go to System → Integrations and check that LuigisboxIntegration status is "Active."
3. Check Luigi's Box Dashboard:
   • Go to the Catalog Browser. Does the product count roughly match your Magento catalog?
4. Verify with Advanced SQL: If you still see a large discrepancy, use this query to get the exact count of products that should be syncing.

-- Count enabled products that are visible in catalog and search
SELECT COUNT(*) as visible_products
FROM catalog_product_entity cpe
-- Join for product status
JOIN catalog_product_entity_int cpei_status
  ON cpe.entity_id = cpei_status.entity_id
-- Join for product visibility
JOIN catalog_product_entity_int cpei_visibility
  ON cpe.entity_id = cpei_visibility.entity_id
WHERE cpei_status.attribute_id = (
    SELECT attribute_id
    FROM eav_attribute
    WHERE attribute_code = 'status'
      AND entity_type_id = 4  -- 4 = 'catalog_product'
)
AND cpei_status.value = 1  -- 1 = Enabled
AND cpei_visibility.attribute_id = (
    SELECT attribute_id
    FROM eav_attribute
    WHERE attribute_code = 'visibility'
      AND entity_type_id = 4  -- 4 = 'catalog_product'
)
AND cpei_visibility.value IN (2, 3, 4);
-- 2 = Catalog, 3 = Search, 4 = Catalog & Search

Issue 2: Data is Outdated (e.g., old prices)

This happens when a change is made in Magento but hasn't been picked up by the sync yet.

Solution:

1. Wait for the 3-Hour Sync Cycle: Just like with new products, updates to existing products are only synced every 3 hours.
2. Check Magento Indexes: Magento's internal data might be stale. Ask your developer to reindex from the command line:

# Reindex Magento
php bin/magento indexer:reindex

# Clear cache
php bin/magento cache:flush

1. Verify "Updated At" Timestamp: You can check if Magento has registered your recent change with this query:

-- Products updated in last 24 hours
SELECT
  cpe.sku,
  cpe.updated_at,
  cpe.type_id
FROM catalog_product_entity cpe
WHERE cpe.updated_at >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
ORDER BY cpe.updated_at DESC
LIMIT 50;

If your product is on this list, it is ready to be picked up on the next sync.

Issue 3: Initial Sync is Taking Too Long

Solution:

This is normal for very large catalogs.

• Be patient: A catalog with > 50,000 products can take several hours for its first sync.
• Check Server Resources: Ensure your server has adequate CPU and memory.
• Check Network: A slow network connection to Luigi's Box can also be a factor.

If your sync has not completed after 24 hours, contact support.

Support & Resources

Self-Service Resources

Luigi's Box Dashboard:

• Check Catalog Browser for product counts and data.

Magento Admin:

• Integration status: System → Extensions → Integrations
• Product visibility: Catalog → Products
• System logs: var/log/system.log, var/log/exception.log

Getting Help

Luigi's Box Support:

• Email: support@luigisbox.com
• Support Portal: https://help.luigisbox.com/