Standard CSV import in 1C-Bitrix breaks on three things: wrong encoding, mismatched delimiters, and missing property mapping. A manager uploads a file, gets "Import completed, 0 items processed" — and writes to support. We configure CSV import and export so that exchange works predictably. The result is a reliable process: from diagnostics to automation. For stores with up to 5,000 products, import takes 1–3 minutes; for 50,000 products, up to 30 minutes with proper cron setup. Using step-by-step mode, you process data without timeouts, and cron automation saves up to 15 hours monthly on manual uploads — at $20/hour, that's $300 savings per month.
Mechanics of CSV Import in the Catalog
The catalog module has a built-in CSV handler — class \Bitrix\Catalog\CsvImport, which implements the StepByStep interface to handle large datasets. Import is available through the admin interface: Store → Settings → Import CSV. But it's important to understand what's under the hood.
Bitrix reads the file line by line, splitting by delimiter (default semicolon). The first line can be a header if the "First line contains field names" option is enabled. Then each line maps to infoblock fields: NAME, XML_ID, DETAIL_TEXT, properties like PROPERTY_ARTICLE, prices CATALOG_PRICE_1.
Critical Settings
- File encoding — Bitrix expects UTF-8. If the file is Windows-1251 (typical for 1C exports), enable recoding or convert the file beforehand. About 80% of CSV import problems are encoding-related.
- Field delimiter — semicolon, comma, or tab. If data contains semicolons (product descriptions), use tab.
-
XML_ID— unique element identifier. Without it, import creates duplicates on each run instead of updating existing records. Approximately 90% of duplicate issues stem from missing XML_ID mapping.
Field and Property Mapping
The most common error is mismatch between CSV headers and infoblock property codes. Bitrix looks for an exact match: if the property is called BRAND and the CSV header is brand, mapping won't work.
For list-type properties, the CSV should contain the value, not the variant's XML_ID. Bitrix tries to find a match by value and link the element. If no value is found, the property remains empty with no log error.
For element-link properties, pass the ID of the linked element or its XML_ID (if the "search by XML_ID" option is enabled).
How to Set Up CSV Export?
Export is configured in Store → Data Export. The export profile is saved in the b_catalog_export table and can be run via cron through the agent \Bitrix\Catalog\CatalogExportAgent::exportCsv.
When exporting large catalogs (over 50,000 products), the standard mechanism works stepwise — 500 elements per iteration. The step size is set in the profile settings. If export stops midway, increase max_execution_time in PHP or reduce the step size.
The export format is fixed: UTF-8, delimiter from profile settings. For integration with external systems expecting Windows-1251, add post-processing via iconv in the cron script.
Product Duplicates: Root Causes
Duplicates are the result of missing a unique identifier. Always fill the XML_ID column and enable search by it. If the source has no ready-made XML_IDs, generate them using a formula: article + manufacturer. This is the only reliable way to ensure repeated import updates existing records.
Property Mapping: Common Mistakes
The reason is column name mismatch. Bitrix looks for an exact match: PROPERTY_<CODE>. If the CSV has Бренд and the property code is BRAND, mapping won't happen. Solution: either rename columns in the CSV, or use an intermediate script to transform headers.
Automation via Cron
Manual import through the admin panel is acceptable for one-time uploads. For regular updates (daily stock/price synchronization), use cron launch. Import via admin panel is 10 times slower than via cron for catalogs over 50,000 products. Additionally, direct SQL import can be up to 5 times faster than the API-based CSV import for catalogs exceeding 50,000 products.
/usr/bin/php -f /home/bitrix/www/bitrix/modules/catalog/load/csv_run.php Import profile parameters are passed via the saved profile ID. The profile is created in the admin panel, tested manually, then its ID is placed in cron.
On one project with a catalog of 20,000 products, the client imported a price list every day. After setting up a profile with article search and step-by-step mode, import time dropped from 3 hours to 10 minutes.
| Catalog size | Import time | Recommendation |
|---|---|---|
| Up to 5,000 products | 1–3 min | Standard import via admin panel |
| 5,000–50,000 | 5–30 min | Cron + step-by-step mode |
| Over 50,000 | 30+ min | Cron + direct SQL import bypassing API |
| Exchange type | Method | Setup complexity |
|---|---|---|
| Manual one-time | Admin panel | Low |
| Regular small | Cron | Medium |
| Regular large | SQL + cron | High |
Typical Pitfalls
- Product duplicates — always fill
XML_IDand enable search by it. Without this, each import run creates new elements. - Lost images — CSV import does not support file uploads. For images, use a path to the file on the server in the
DETAIL_PICTUREcolumn — Bitrix will pick up the file by absolute path. - SEO fields reset — if the CSV lacks
META_TITLE,META_DESCRIPTIONcolumns, import may reset them on update. Enable the "Do not update empty fields" option.
What's Included in the Work?
- Audit of current CSV exchange (encoding, structure, profiles).
- Configuration of field and property mapping for the infoblock.
- Creation of import/export profile considering data volumes.
- Performance optimization (step-by-step mode, cron).
- Documentation of settings and staff training.
- Post-release support (bug fixes, fine-tuning).
Our team has 10+ years of experience in Bitrix development and has completed over 200 CSV exchange integration projects. This experience guarantees correct exchange operation. If you have questions about setting up CSV import or export, contact us — we'll assess your project and offer a solution. Get a consultation right now.
For more on CSV format, see Wikipedia.