Setting up CSV import and export in 1C-Bitrix

Setting Up CSV Import and Export in 1C-Bitrix

Standard CSV import in 1C-Bitrix breaks on three things: incorrect encoding, separator mismatch and missing property mapping. Manager uploads file, gets "Import complete, 0 items processed" — and writes to support. Let's understand how to set up CSV exchange so it works predictably.

CSV Import Mechanics in Catalog

catalog module contains built-in CSV handler — class \Bitrix\Catalog\CsvImport. Import available via admin interface: Shop → Settings → CSV Import. But important to understand what happens under hood.

Bitrix reads file line by line, splitting by separator (default semicolon). First line may be header — if "First line contains field names" option enabled. Next each line maps to infoblock fields: NAME, XML_ID, DETAIL_TEXT, properties like PROPERTY_ARTICLE, prices CATALOG_PRICE_1.

Critically important settings:

• File encoding — Bitrix expects UTF-8. If file in Windows-1251 (typical for 1C export), need enable re-encoding in import settings or convert file beforehand.
• Field separator — 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.

Field and Property Mapping

Most common mistake — header mismatch with infoblock property codes. Bitrix searches exact match: if property named BRAND, but CSV header brand — mapping won't work.

For "list" type properties in CSV need specify value, not variant XML_ID. Bitrix tries to find match by value and bind element. If value not found — property stays empty without any log error.

Properties of "element binding" type require passing ID of linked element or its XML_ID (with option enabled for XML_ID search).

CSV Export

Export configured in Shop → Export Data. Export profile saved in b_catalog_export table and can run via cron via \Bitrix\Catalog\CatalogExportAgent::exportCsv agent.

When exporting large catalogs (over 50,000 products) standard mechanism works step-by-step — 500 elements per iteration. Step size configured in profile settings. If export breaks mid-way — increase max_execution_time in PHP or decrease step size.

Export format fixed: UTF-8, separator from profile settings. For integration with external systems expecting Windows-1251, add post-processing via iconv in cron script.

Automation via Cron

Manual import via admin allowed for one-time uploads. For regular updates (daily inventory/price sync) use cron run:

/usr/bin/php -f /home/bitrix/www/bitrix/modules/catalog/load/csv_run.php

Import profile parameters passed via saved profile ID. Profile created in admin, tested manually, then its ID substituted in cron.

Typical Pitfalls

• Product duplicates — always fill XML_ID and enable search by it. Without this every import run creates new elements.
• Lost images — CSV import doesn't support file uploads. For pictures use path to file on server in DETAIL_PICTURE column — Bitrix picks up file by absolute path.
• SEO fields reset — if CSV missing META_TITLE, META_DESCRIPTION columns, import may clear them on update. Enable "Don't update empty fields" option.