Magento Open Source product and customer CSV import

The short answer is that an uploaded file does not change the storefront directly. It moves through a sequence of checks and stages, and each stage can reject or delay rows. In Magento Open Source, the admin uploads a CSV through the import page, the system checks the file format and the header row, then validates each row against the fields and attribute definitions for the entity type. Rows that fail are reported individually while others may still be processed, depending on the error handling settings you choose. Plan for the reader of the error report to be someone on the merchandising or operations team, not the developer who built the template.

Validation happens in two layers. The first layer covers the file: encoding, delimiter, column headers and whether the required columns exist. The second covers the content of each row, such as whether a SKU is valid, whether a value fits the attribute's input type, and whether a select or multiselect value matches an existing option. Attribute sets matter here. A column that is valid for one attribute set can be meaningless for another, and a product that is assigned to a set without a required attribute can fail even when the row looks complete. Store scopes add a further trap: a value written in the default scope applies everywhere unless a store view row overrides it, so a single missing or mistyped store code can change results on one storefront only. Customer groups and website codes work the same way for customer and price data.

When validation passes, the import run writes the data to the database in batches. Confirm with your store's configuration guide how batch processing, error limits and the point at which a run stops are handled for your version, because these behaviours have changed across releases and should not be assumed from older forum posts. Ask your team to test a run on a copy of production that uses the exact file template and settings you will use live. Keep the original file and the error report together so that a rerun does not duplicate or overwrite records you did not intend to change.

Saved data does not automatically appear on the storefront. Indexers recalculate the data used for category listings, search, price and stock status, and the full-page cache and block cache may continue to serve old pages until they are invalidated or expire. Confirm which indexers are set to update on save and which run on schedule, and check how your cache setup, including Varnish for self-managed installations, handles invalidation after an import. Plan a verification step on the storefront for a sample of products in each store view and customer group, because a catalog can look correct in the admin while the public pages still show earlier data.

The exact validation messages, error limits and processing behaviour should be confirmed against the release notes and configuration guide for the version your store runs. The official Adobe documentation is also the reference for current file templates and the column names each entity type accepts, so build your import files from those templates rather than from an old export. Treat any sample file in this article as illustrative only.

Product images, customer addresses and stock source files fail for reasons that have little to do with the column layout of the CSV. Each one depends on something outside the file: image paths depend on what is physically present in the media directory when the import runs, addresses depend on a customer record that already exists, and stock rows depend on source codes and quantities that match the inventory configuration. Before the team runs a file, it should confirm that each dependency is satisfied in the target environment, because the import will not always stop with a clear message when one is missing.

For product images, the file usually holds relative paths that Magento resolves against the media directory of the installation. The team should confirm how the images get there. Ask whether the image files are copied into the media directory before the import starts, whether they are staged by a separate deployment step, and whether the storage layer (local disk, a shared network mount or object storage behind a sync process) is the same one the web and worker nodes read from. A path that resolves on one application server and not on another is a common source of partial catalogs. Also confirm the file naming convention, case sensitivity on the Linux host and the handling of duplicate filenames across product SKUs, since these details cause silent misassignment rather than hard errors.

Customer address rows reference a customer through an identifier such as the email address and website scope. An address written before its parent customer exists, or written under the wrong website scope, is a dependency problem, not a formatting problem. Confirm the import order the team plans to use (customers first, then addresses), whether the customer file and the address file share the same identifier, and how the import treats an address row whose parent cannot be found: whether it is skipped, reported as an error or counted against the error limit. The answer decides whether a failed run needs a rerun of the whole file or only the rejected rows, and whether the error report gives enough detail to fix the source data without guessing.

Stock source files need the same scrutiny. Each row carries a SKU, a source code and a quantity, and those values must line up with the inventory sources and the stock configuration already defined in the store. Confirm that every source code in the file exists as an active source, that the SKUs exist in the catalog before the stock file runs, and that the team understands whether a quantity of zero, a blank status or a negative value is accepted, rejected or read differently. Also confirm whether inventory indexing runs as part of the import or afterward, because stock shown on the storefront can lag the file if indexers are not in the expected state. Record the expected results for a small test file before running production data.

A one-time import is a project. A recurring import from an ERP or PIM is an operating process, and most of the damage happens on the second or third run, when someone changes a column, a stock feed lags, or a job overlaps with a catalog reindex. Plan the schedule, the file handling and the failure response before the first scheduled run, and treat each run as a change to production data.

Schedule loads outside peak trading hours and keep them out of windows where indexers, cache refreshes or ERP exports are already running. Confirm with your own team which cron jobs, index jobs and message queue consumers are active at each hour, and record the agreed window in the runbook. Keep a known-good source file from the last successful run, with its checksum, so you can re-import it or compare against it when a later file misbehaves. Decide in advance who may trigger a rollback, what rollback means for your data (re-importing the prior file in Add/Update mode, or restoring a database backup), and how long the team will wait before choosing one.

Review the error report on every run, not only when the job fails visibly. The import page in the Magento Open Source admin reports rows that were skipped or rejected, and a run can finish with a large error count and still look successful. Set an error threshold that stops the team from accepting a file with a high share of bad rows, and route the error file to the owner of the source system. Separate the feeds that change often from the feeds that define structure: price and stock files are usually small and frequent, while full product rebuilds that change attribute sets, categories or URL keys should run less often and with a fuller review. Keep these in separate jobs so a stock feed failure does not block a catalog correction.

A scheduled file import stops being the right tool when changes are small, frequent and need per-record status, such as stock or price updates several times a day that a warehouse or pricing team must confirm. In that case, compare the asynchronous and bulk REST APIs, which return status for each batch and fit queue-based retries, and a scheduled job that feeds the same logic with its own logging. Note that the CSV import is a single file processed as a whole, so partial success and retry handling are your responsibility. Confirm with your Magento Open Source version's documentation which endpoints and consumers are available in your release, because the API surface differs between 2.4.x lines.

Before you commit to any schedule, measure run duration and error rates in your own staging environment with a copy of production-sized data, on the same PHP, MySQL or MariaDB, OpenSearch and RabbitMQ versions you run in production. Record how long each feed takes, how many rows fail on a typical day and on a bad day, and how long reindexing takes after each load. Use those numbers to set the window, the error threshold and the rollback deadline. Do not carry timings from another store into your plan, because catalog size, attribute count and hardware change them substantially.