Configure Magento 2 KatanaPIM integration

Complete settings reference for the KatanaPIM Connect extension. This guide explains each setting and when to use it.

General Configuration

Navigate to Stores → Configuration → Katana PIM → General or via the admin menu Katana PIM → Configuration.

General

Setting	Description
Enabled	Master switch for the KatanaPIM integration

When to disable: Only disable if you need to temporarily stop all PIM synchronization without uninstalling the module. Useful during major catalog restructuring or PIM migrations.

API

Connect your Magento store to your KatanaPIM instance.

Setting	Description
URL	Your KatanaPIM instance URL (e.g., `https://yourcompany.katanapim.com`)
Key	API key from your KatanaPIM account (stored encrypted)
Test Credentials	Validates your API connection

Where to find your API key: In KatanaPIM, navigate to your account settings or contact your KatanaPIM administrator.

Tip: Always test credentials after entering them. A failed connection will prevent all synchronization.

Import Settings

Fine-tune how the extension processes data during synchronization.

Reindex Data

Setting	Description
Init Reindex after full sync	Automatically trigger Magento reindex after completing a full sync

Warning: Not recommended for production stores with large catalogs. Reindexing can cause performance issues during business hours. Instead, schedule reindex via cron during off-peak times.

When to enable: Only on development/staging environments, or small catalogs where reindex completes quickly.

Store Filter

If your KatanaPIM account has multiple stores, you can filter which store's data to import.

Setting	Description
Import Stores	Fetches available stores from KatanaPIM
Limit to Katana Store	Select which KatanaPIM store to sync from

When to use: Multi-brand setups where different Magento instances connect to different KatanaPIM stores. Leave empty to import from all stores.

Default Websites

Setting	Description
Default Websites	Fallback websites for new products and categories when no store mapping is available

Important: This only affects NEW products and categories. Existing entities keep their current website assignments. Used by both product and category imports.

Limits

Controls batch sizes, cron processing limits, mass action thresholds, and async concurrency.

Batch Sizes

Control how many entities are processed per batch.

Setting	Default	Description
API Page Size	1000	Number of items to fetch from Katana API per request (applies to all entities)
Magento Batch Size	20	Number of items to sync to Magento per batch (applies to all entities)

When to adjust:

Lower values if you experience memory errors or timeouts during sync
Higher values if you have a powerful server and want faster imports

Cron Limits

Control how many entities are processed per cron run. Set to 0 for unlimited.

Setting	Default	Description
Max Products per Cron	100	Maximum products to process per cron run
Max Categories per Cron	100	Maximum categories to process per cron run
Max Attributes per Cron	100	Maximum attributes to process per cron run
Max Assets per Cron	100	Maximum assets to process per cron run

When to adjust: Increase if your cron window is long enough and the server can handle it. Decrease if cron jobs overlap or cause timeouts.

Mass Action

Setting	Default	Description
Mass Action Limit	150	Maximum number of records that can be processed in a single mass action

Async Settings

Setting	Default	Description
Concurrency Limit	1	Page requests the admin sync sends at the same time

When to adjust: Raise this only if an import through the admin is too slow and your server has PHP-FPM workers to spare. Every simultaneous request occupies a worker for the length of its page, so a high value can make the admin unresponsive for everyone else while an import runs. Lower it again if you see Redis or database connection errors.

Note: the admin sync is driven by the browser, so the page has to stay open until it finishes. For large catalogues use the cron instead (see Automation).

Store Languages

Map KatanaPIM languages to your Magento store views for multi-language product data synchronization.

Setting	Description
Store Language Mapping	Map KatanaPIM language codes to Magento store views

Finding Your KatanaPIM Language Codes

In your KatanaPIM backend, navigate to Configuration > Languages to see all available languages and their codes.

Common language code formats:

nl-NL - Dutch (Netherlands)
en-US - English (United States)
fr-FR - French (France)
de-DE - German (Germany)
it-IT - Italian (Italy)
es-ES - Spanish (Spain)

Mapping the Default Language

To map KatanaPIM's default language (marked with checkmark in "Is default" column), use the string default (lowercase) as the Katana Language Code.

Example mapping:

Katana Language Code	Magento Store View
`default`	English (Default Store View)
`nl-NL`	Dutch
`de-DE`	German

How It Works

When products sync, the extension checks which languages are mapped
For each mapped language, it pulls the translated product data from KatanaPIM
The data is saved to the corresponding Magento store view
Unmapped languages are ignored during sync

Tip: Only map languages you actually use in Magento. Mapping unused languages increases sync time without benefit.

Debug & Logging

Setting	Description
Debug Mode	Enable detailed logging for troubleshooting
View Logs	Download debug and error logs directly from admin

Log locations:

Debug log: var/log/katanapim/debug.log
Error log: var/log/katanapim/error.log

When to enable: Only when troubleshooting issues. Debug mode logs extensive information and can grow large quickly. Disable after resolving issues.

Product Data Configuration

Navigate to Stores → Configuration → Katana PIM → Product Data.

These settings control how product data flows from KatanaPIM to Magento.

General

Setting	Description
Enable Product Import	Master switch for product synchronization
Only import published products	When enabled, only products marked as Published in KatanaPIM are imported. Unpublished products are skipped during sync. (New in 3.10.0)
If SKU exists update product	Link existing Magento products to KatanaPIM by matching SKU
SKU Fallback	When a product has no SKU in KatanaPIM (e.g. configurable products), this value is used as the Magento SKU. Options: External Key (uses the product's external key code) or KatanaPIM ID (uses the numeric KatanaPIM product ID). (New in 3.10.0)
Configurable Product Level	Controls which hierarchy level becomes the configurable product. GrandParent: GrandParent = configurable, Parent = skipped. Parent: Parent = configurable, GrandParent = skipped. Both: Both levels become configurable products.
Website Assignment Source	Controls how products are assigned to Magento websites. Katana Stores (default): uses the product's LimitedToStores and the Store Mapping grid. Katana Attribute (legacy): uses the katanapim_product_in_websites attribute. See Product Website Matching. (New in 3.10.0)
Sync Related Products	When enabled, related product assignments from KatanaPIM are synced to Magento. Disable to manage related products manually in Magento. (New in 3.10.0)
Sync Cross-sell Products	When enabled, cross-sell assignments from KatanaPIM are synced to Magento. KatanaPIM owns the list while this is on: cross-sells assigned by hand in Magento are replaced on the next sync. Off by default, so switching it on is a deliberate step. (New in 3.12.0)

SKU matching explained: When enabled, if a product in KatanaPIM has the same SKU as an existing Magento product, they'll be linked. Future syncs will update that Magento product instead of creating a duplicate.

When to enable SKU matching:

Migrating from another PIM system
Connecting KatanaPIM to an existing catalog
Merging product data sources

When to disable: Fresh installations where all products come from KatanaPIM.

Attributes

Map KatanaPIM attributes to core Magento product fields. Select which KatanaPIM attribute should populate each Magento field.

Setting	Maps to Magento field
Name	`name`
Short Description	`short_description`
Description	`description`
GTIN	Custom attribute for EAN/UPC codes
Manufacturer Part Number	Custom attribute for MPN
Attachments	Product attachments/downloads
Meta Keywords	`meta_keyword`
Meta Description	`meta_description`
Meta Title	`meta_title`

Tip: These dropdowns show all available KatanaPIM attributes. If you don't see the attribute you need, run an attribute import first from Katana PIM → Attributes.

Asset Data

Control how images and videos from KatanaPIM are handled.

Setting	Description
Import Video to Gallery	Include videos in the product media gallery
Title Attribute	KatanaPIM attribute to use as video title
Gallery Position	Where videos appear in the gallery (lower = first)
Compare Image Hash	Only re-import images if content changed

Image hash comparison: When enabled, the extension compares file hashes before importing. This prevents re-downloading identical images and speeds up incremental syncs significantly.

When to disable hash comparison: If images in PIM are being updated but hashes aren't changing (rare), or during initial import for speed.

Product Import Defaults

Set default values for newly created products. These apply only when creating products - existing products are not affected.

Setting	Options	Recommendation
Status	Enabled / Disabled	Disabled - Review products before making them live
Visibility	Not Visible / Catalog / Search / Both	Not Visible - Enable after QA
Use config manage stock	Yes / No	Yes - Use global inventory settings
Is in stock	Yes / No	Yes - Unless you manage stock separately

Recommended workflow: Import products as Disabled/Not Visible, review them in Magento, then enable in bulk after QA.

Price Updates

Setting	Description
Update product price changes	Sync price and cost from PIM
Update special price	When enabled, special_price is synced from PIM. When disabled, special_price in Magento is not overwritten during sync. Useful when special prices are managed manually or via a different source. Only visible when price updates are enabled. (New in 3.10.0)

When to disable price updates: If prices are managed in Magento (promotions, customer-specific pricing) rather than PIM. Enabling this will overwrite any Magento-side price changes.

When to disable special price sync: If you manage special prices / sale prices in Magento (e.g. via catalog price rules or manual entry) while base prices come from PIM.

Website Price Mapping (New in 3.8.0)

Map KatanaPIM price attributes to specific Magento websites. This allows you to set different prices per website from PIM.

Setting	Description
Katana Attribute	The KatanaPIM price attribute (e.g., `Price_DE`, `Price_FR`, `Price_NL`)
Magento Website	The Magento website where this price should be applied

Prerequisites:

Catalog Price Scope must be set to Website (Stores → Configuration → Catalog → Catalog → Price)
Update product price changes must be enabled

How it works:

The base price (Default Config scope) is always set from the default PIM price field
Website-specific prices are set from the mapped PIM attributes
Prices are applied to all store views within the mapped website
If a mapped attribute has no value or is empty, the product uses the base price for that website

Example configuration:

Katana Attribute	Magento Website
`Price_NL`	Dutch Website
`Price_DE`	German Website
`Price_FR`	French Website

Setting up price attributes in KatanaPIM:

Create custom attributes in KatanaPIM for each website price (e.g., Price_NL, Price_DE)
These should be numeric/decimal attributes
Fill in the prices per product in KatanaPIM
Map them in this configuration

When to use:

Multi-website Magento setups with different pricing per region/country
B2B setups with different customer group websites
Multi-currency setups where prices are managed per website

When NOT to use:

Single-website Magento installations
When Catalog Price Scope is set to "Global"
When prices are identical across all websites

Category Data Configuration

Navigate to Stores → Configuration → Katana PIM → Category Data.

General

Setting	Description
Enable Category Import	Master switch for category synchronization
If name exists link category	Match existing Magento categories by name and depth
Default Store View for Category Tree	Used to pick the root category tree when a Katana category has no Stores filter, or when its filter spans store views that belong to multiple root categories. Leave empty to use the system default store view.

Category matching explained: When enabled, if a KatanaPIM category has the same name as a Magento category at the same tree depth, they're linked. This preserves your existing category URLs and SEO.

Example: KatanaPIM category "Clothing > Shirts" will match Magento category "Clothing > Shirts" if both are at depth 2.

When to enable: Connecting KatanaPIM to an existing catalog with established categories.

When to disable: Fresh installations, or if you want completely separate category structures.

Automation Configuration

Navigate to Stores → Configuration → Katana PIM → Automation.

Automate synchronization via Magento cron jobs.

Settings

Setting	Description
Enable Automation	Master switch for cron-based sync
Auto create new products	Allow cron to create new Magento products
Auto create new categories	Allow cron to create new Magento categories

Auto-create settings: Control whether the automated sync can create new entities or only update existing ones.

Conservative approach: Disable auto-create initially. New products appear in the Katana PIM grid but aren't created in Magento until you manually approve them.

Hands-off approach: Enable both for fully automated catalog management. New products in PIM automatically appear in Magento.

Cron Settings

Setting	Description
Full Update	Complete resync of all data
Incremental Update	Sync only changes since last update

Recommended schedule:

Full Update: Weekly or daily (off-peak hours)
Incremental Update: Every 1-4 hours

Full vs Incremental:

Full sync fetches everything from PIM, ensuring Magento matches PIM exactly. Slower but catches any missed changes.
Incremental sync only fetches items modified since the last sync. Much faster for day-to-day updates.

Tip: If products seem out of sync, run a manual full sync from the admin grid or CLI.

Need More Help?

Documentation:

All Help Articles - Complete documentation overview

Support:

Contact Support - Get help from our team