The CSV Field Mapper add-on provides a flexible way to map third-party CSV / TSV / DSV files to X-Cart’s internal product fields and automate price and inventory updates. It is designed for merchants who regularly receive product data from external suppliers and need a consistent way to align external CSV structures with X-Cart’s import requirements.
The add-on is available for:
X-Cart 5.5.1.53 and later
X-Cart 5.6.0.2 and later
Although the underlying workflow is the same across both versions, the field sets and template structure differ slightly due to changes in product data architecture.
What the add-on does
The CSV Field Mapper add-on allows you to:
Upload a supplier's CSV, TSV, or DSV file
Map the supplier’s column names to X-Cart product fields
Save this mapping as a reusable Import Template
Use the template repeatedly to update information in their store with incoming supplier data
Supported file formats:
CSV (comma-separated values)
TSV (tab-separated values)
DSV (delimiter-separated values)
Supported data fields:
MPN (Manufacturer Part Number)
UPC (Barcode)
stockLevel (5.5.1.53+)
price (5.5.1.53+)
manualPrice (5.6.0.2+)
costPrice (5.6.0.2+)
<location_code>array (5.6.0.2+)
💡MPN and UPC fields are provided by the Barcode and Manufacturer Part Number fields add-on, which must be enabled to use the mapper.
Product identification logic
The import engine matches supplier data to existing products using MPN or UPC:
You must choose one of these fields as the Product mapping ID when creating a template.
This field is never updated during import — it is used strictly for product lookup.
How matching works:
A product is considered found if at least one of the selected identifiers matches (logical OR).
UPC is globally unique → brand selection optional.
MPN is unique only within a brand → brand selection is required for accurate lookup.
Thus, when running imports:
Templates based on MPN will show a Brand selector, which must be set to ensure a correct 1:1 match.
Templates based on UPC may use the brand selector optionally (recommended when suppliers reuse UPC values).
This ensures accurate product identification during updates.
Why templates only update existing products
Whenever an Import Template is selected, X-Cart automatically forces the import mode "Update existing items, but skip new items".
This restriction exists because supplier CSV files often lack essential fields required to create new products in X-Cart; for example:
SKU
Product name
The mapper does not allow creating new product records if a mandatory field is missing.
Key differences between X-Cart 5.5.1 and 5.6.0
X-Cart 5.5.1
Prices and stock are updated from the same CSV file
One template may contain all mappable fields
Supported fields: MPN, UPC, price, stockLevel
X-Cart 5.6.0
Templates must explicitly target either Price or Inventory
Price templates include: MPN, UPC, manualPrice, costPrice
Inventory templates include: MPN, UPC,
<location_code>The template type is selected during creation and cannot be changed later.
How it works
The workflow consists of two major steps:
Create an Import Template
Run an import using the saved template
Once the template is created, you can reuse it indefinitely — you only need to upload a new CSV from the supplier each time.
Enabling the add-on
To begin, install and enable the CSV Field Mapper add-on.
After installation, the template management interface becomes available under:
Catalog → Import & Export → Import Templates
Creating an import template
Creating a template is a two-step process.
Step 1 — Upload the supplier file and choose product lookup field
On the template creation page:
Name your template. A name is required.
Choose the Product mapping ID. This ID determines how X-Cart finds matching products during import:
MPN (default)
UPC
This field is never updated during import; it is used strictly for product identification.
If you are using X-Cart 5.6.0+, you must also choose the Data type:
Price
Inventory
Upload the supplier CSV/ TSV / DSV file. The file must:
File must contain column headers
Max size: 128 MB
If the file has no headers, template creation stops with: “No column headers found. Column headers are required to map the file structure and create an import template.”
Step 2 — Map X-Cart fields to supplier columns
In this step, you define which supplier columns correspond to X-Cart’s product fields.
The mapping table displays:
X-Cart product field (e.g., MPN, UPC, price)
CSV product field — a dropdown listing all detected column names
Preview — shows a sample value from that column (if available)
Automatic matching
X-Cart attempts to match fields using case-insensitive partial name matching, e.g.:
stockLevel → columns containing “qty”, “QTY”, “quantity”
MPN → “MPN”, “mpn”, “Mpn”
UPC → “UPC”, “upc”, etc.
Unmatched fields can be mapped manually.
Required fields
The field selected as Product mapping ID (MPN or UPC) is always required and marked with an asterisk. You cannot save the template until it is mapped.
Once all required fields are mapped, save the template.
A template remains marked Not configured until all required fields are mapped.
After configuration is complete, it changes to Template is configured.
Using a template to import data
To perform an import using a saved template, go to:
Catalog → Import & Export → Import
Upload a supplier CSV/TSV/DSV file
Open Advanced settings
Choose the desired Import template. Only fully configured templates appear in the list.
If the template is based on MPN, select the Brand for matching.
If the template uses UPC, selecting a Brand is optional (Selecting a Brand prevents unexpected matches where different brands share the same UPC. “All brands” is also available if you intentionally want a broader match scope.)
Import mode switches automatically to Update existing items, but skip new items.
Run the import
If the structure of the uploaded file does not match the template (e.g., missing required columns), X-Cart will display “X-Cart could not find data in your file.”
Result handling and error messages
Errors may occur if:
Required mapped fields are missing
The uploaded file lacks expected columns
The file format does not match the template
Supplier data includes invalid values
X-Cart will display an error summary similar to the standard CSV Import report.
Best practices
Use MPN when possible — it is less likely to cause ambiguous matches.
Create separate templates for each supplier to avoid mapping conflicts.
For X-Cart 5.6.0+, maintain two templates per supplier:
Price Template
Inventory Template
This ensures clean data separation and prevents accidental overwrites.
Can't find answers you're looking for?
Email us at support@x-cart.com. We will be happy to help!
Related articles