Skip to main content

Magento 2 Installation Guide

Connect your Magento 2 or Adobe Commerce store to Synton AI for enterprise-grade AI commerce management.

Prerequisites​

Verify your environment before installation:

RequirementMinimum Version
Magento Open Source2.4.4+
Adobe Commerce2.4.4+ (Cloud or On-Premise)
PHP8.1+
MySQL8.0+ or MariaDB 10.6+
Elasticsearch/OpenSearch7.17+ / 2.x
Composer2.x
SSL CertificateRequired (HTTPS)
Adobe Commerce Support

All features work with both Magento Open Source and Adobe Commerce. B2B features require Adobe Commerce with B2B module enabled.

Step 1: Create Synton AI Account​

  1. Visit app.synton.ai
  2. Click Sign Up
  3. Select Magento as your platform
  4. Complete registration
  5. Verify your email address

Step 2: Install Extension via Composer​

Connect to your Magento server via SSH:

# Navigate to Magento root directory
cd /path/to/magento

# Add Synton AI repository
composer config repositories.syntonai composer https://packages.synton.ai/magento

# Install the extension
composer require synton/module-ai:^1.0

# Enable the module
bin/magento module:enable Synton_Ai

# Run setup upgrade
bin/magento setup:upgrade

# Compile dependency injection (production mode)
bin/magento setup:di:compile

# Deploy static content (production mode)
bin/magento setup:static-content:deploy

# Clear cache
bin/magento cache:flush
Development Mode

If running in developer mode, you can skip setup:di:compile and setup:static-content:deploy steps.

Installation Verification​

Verify the module is installed:

bin/magento module:status Synton_Ai

Output should show: Module is enabled

Step 3: Create Integration Token​

  1. Log into Magento Admin Panel
  2. Navigate to System > Extensions > Integrations
  3. Click Add New Integration

Configure Integration​

Integration Info Tab:

FieldValue
NameSynton AI
EmailYour admin email
Callback URLhttps://api.synton.ai/integrations/magento/callback
Identity Link URLhttps://api.synton.ai/integrations/magento/identity

API Tab - Set permissions:

ResourceAccess Level
Catalog > InventoryAll
Catalog > ProductsAll
Catalog > CategoriesRead
Sales > OrdersRead
Sales > InvoicesRead
Sales > ShipmentsRead
CustomersRead
Stores > SettingsRead
Stores > AttributesRead
Quick Setup

Instead of selecting individual permissions, you can select:

  • Resource Access: Custom
  • Then check the resources listed above
  1. Click Save
  2. Click Activate to activate the integration
  3. In the confirmation dialog, click Allow

Copy Access Token​

After activation, Magento displays your integration credentials:

  • Consumer Key
  • Consumer Secret
  • Access Token
  • Access Token Secret
Save Credentials

Copy the Access Token - you'll need it in the next step. You can retrieve it later from the integrations page if needed.

Step 4: Connect to Synton AI​

  1. Open app.synton.ai in a new browser tab
  2. Navigate to Settings > Integrations
  3. Click the Magento card
  4. Enter your credentials:
    • Store URL: Your Magento store URL (e.g., https://store.example.com)
    • Access Token: The integration token from Step 3
  5. Click Connect
  6. Wait for connection verification (10-15 seconds)

Step 5: Configure Extension Settings​

In Magento Admin, navigate to Stores > Configuration > Synton AI > General:

SettingDescriptionRecommended
EnableModule activationYes
Sync ModeReal-time or scheduledReal-time
Include Disabled ProductsSync disabled productsNo
Order History RangeHistorical import90 days
Debug ModeEnable detailed loggingNo (unless troubleshooting)

Click Save Config at the top right.

Configuration Scope

Most settings can be configured per Website, Store, or Store View. Use the scope dropdown in the top left to configure different values per scope.

Verification​

Check Connection Status​

  1. In Synton dashboard, go to Settings > Integrations > Magento
  2. Verify status shows Connected with green indicator
  3. Click Test Connection
  4. You should see:
    • ✅ API Connection Successful
    • ✅ Products Readable
    • ✅ Orders Readable
    • ✅ Integration Active

Verify Data Sync​

  1. In Synton AI dashboard, navigate to Chat
  2. Ask: "How many products do I have?"
  3. Verify the count matches your Magento catalog (simple + configurable)
  4. Ask: "Show me recent orders"
  5. Verify orders display with correct data

Test REST API Access​

Open a browser and test the Magento REST API:

https://yourstore.com/rest/V1/store/storeConfigs

You should see JSON configuration data, not an error.

Multi-Store Configuration​

For multi-website/store/store-view setups:

Website Level​

Configure API credentials per website:

  1. In Magento Admin, switch scope to specific website
  2. Go to Stores > Configuration > Synton AI
  3. Uncheck Use Default for settings you want to customize
  4. Configure website-specific settings
  5. Save

Store View Level​

Configure language and currency:

  1. Switch scope to specific store view
  2. Set language mappings for multi-language ads
  3. Set primary currency for reporting

Configuration Hierarchy​

Global (Default Config)
├── Website 1 (US)
│   ├── Store 1 (Main Store)
│   │   ├── Store View EN-US (English)
│   │   └── Store View ES-US (Spanish)
│   └── Store 2 (Outlet Store)
│       └── Store View EN-US
└── Website 2 (EU)
    └── Store 3 (European Store)
        ├── Store View EN-GB (English)
        ├── Store View FR-FR (French)
        └── Store View DE-DE (German)

Each level can have independent Synton configuration.

Multi-Source Inventory (MSI)​

If using Magento MSI for multiple warehouses:

  1. In Synton, go to Settings > Integrations > Magento
  2. Click Inventory Sources
  3. Map each Magento source to a Synton location:
    • Default Source → Main Warehouse
    • NY Warehouse → New York DC
    • LA Warehouse → Los Angeles DC
  4. Configure per-source alert thresholds
  5. Click Save

Synton will track inventory separately per source and can pause ads when specific sources run low.

Initial Sync​

After connection, an initial sync begins automatically:

  1. In Synton, go to Settings > Integrations > Magento
  2. Monitor Initial Sync Progress
  3. Sync time depends on catalog size:
    • Small (< 100 products): 2-5 minutes
    • Medium (100-1,000 products): 10-20 minutes
    • Large (1,000-10,000 products): 1-3 hours
    • Very large (> 10,000 products): 4-12 hours
Performance Tip

Run initial sync during off-peak hours to minimize impact on server resources.

Troubleshooting​

"Could not connect to Magento API"​

Solutions:

  1. Verify store URL is accessible externally (not localhost)
  2. Check integration is Active in Magento admin
  3. Confirm firewall isn't blocking API requests
  4. Test REST API manually: 
    curl https://yourstore.com/rest/V1/store/storeConfigs
  5. Check Magento logs: var/log/system.log

"Authentication failed"​

Solutions:

  1. Verify integration is Active in System > Integrations
  2. Check Access Token is correct
  3. Confirm API permissions include all required resources
  4. Try regenerating integration:
    • Deactivate and reactivate in Magento
    • Copy new token to Synton
  5. Review var/log/system.log for authentication errors

Products not syncing​

Solutions:

  1. Verify products have Status: Enabled
  2. Check products are assigned to a website
  3. Verify stock status and visibility settings
  4. Check indexer status: 
    bin/magento indexer:status
  5. Reindex if needed: 
    bin/magento indexer:reindex catalog_product_flat
    bin/magento indexer:reindex cataloginventory_stock

Attributes missing​

Solutions:

  1. Verify attribute is Visible on Catalog Pages Front-end
  2. Check attribute is in product's attribute set
  3. Confirm attribute has value assigned to product
  4. Try manual sync in Synton dashboard

Slow initial sync​

Causes: Large catalogs, server resources

Solutions:

  1. Large catalogs can take hours - this is normal
  2. Run during off-peak hours
  3. Switch to Scheduled sync mode instead of real-time
  4. Check Elasticsearch/OpenSearch health: 
    curl http://localhost:9200/_cluster/health
  5. Monitor server resources (CPU, memory, disk I/O)

High server load during sync​

Solutions:

  1. Adjust sync batch size in configuration:
    • Stores > Configuration > Synton AI > Performance
    • Reduce batch size from 100 to 50
  2. Use "Update by Schedule" indexer mode: 
    bin/magento indexer:set-mode schedule
  3. Run sync during off-hours
  4. Consider upgrading server resources

Indexer shows "Invalid" status​

Solutions:

# Check indexer status
bin/magento indexer:status

# Reindex specific indexers
bin/magento indexer:reindex catalog_product_flat
bin/magento indexer:reindex cataloginventory_stock
bin/magento indexer:reindex catalog_category_product
bin/magento indexer:reindex catalog_product_price

# Or reindex all
bin/magento indexer:reindex

Adobe Commerce Cloud​

For Adobe Commerce Cloud deployments:

Add to Environment Configuration​

Edit .magento.env.yaml:

stage:
  deploy:
    SYNTON_AI_TOKEN:
      from_variable: SYNTON_AI_TOKEN

Set the environment variable:

magento-cloud variable:create \
  --level environment \
  --name SYNTON_AI_TOKEN \
  --value "your_access_token" \
  --environment master

Update Build Configuration​

Edit .magento.app.yaml build hook:

hooks:
  build: |
    set -e
    composer config repositories.syntonai composer https://packages.synton.ai/magento
    composer require synton/module-ai:^1.0

Deploy​

git add .magento.env.yaml .magento.app.yaml
git commit -m "Add Synton AI extension"
git push origin master

CLI Commands​

The extension provides useful CLI commands:

# Trigger manual product sync
bin/magento synton:sync:products

# Check connection status
bin/magento synton:status

# View sync statistics
bin/magento synton:sync:stats

# Clear sync queue
bin/magento synton:queue:clear

# View sync logs
bin/magento synton:log:view --lines 50

Extension Compatibility​

Compatible Extensions​

Works with:

  • Magento PageBuilder
  • Adobe Stock Integration
  • Amazon Sales Channel
  • MSI (Multi-Source Inventory)
  • Popular payment gateways
  • Shipping extensions

Known Conflicts​

ExtensionIssueSolution
Custom REST API overridesMay break syncWhitelist Synton endpoints
Heavy Full Page CacheCached API responsesExclude /rest/V1/synton/
Custom inventory modulesStock sync conflictsConfigure data source priority

Uninstallation​

To remove the extension:

Via Command Line​

# Disable module
bin/magento module:disable Synton_Ai

# Remove package
composer remove synton/module-ai

# Run setup upgrade
bin/magento setup:upgrade

# Compile (if production)
bin/magento setup:di:compile

# Clear cache
bin/magento cache:flush

Via Admin Panel​

  1. Go to System > Extensions > Integrations
  2. Find Synton AI
  3. Click Delete
  4. Confirm deletion

In Synton Dashboard​

  1. Go to Settings > Integrations
  2. Find Magento card
  3. Click Disconnect
  4. Confirm disconnection
Data Retention

Synced data remains in Synton for reporting purposes unless you request deletion. Contact support@synton.ai to delete all data.

Next Steps​

  1. Open Your Dashboard at app.synton.ai
  2. Complete Onboarding — Follow the guided setup in your dashboard
  3. Explore AI Agents — Let Synton start analyzing and optimizing your store

Support​