Prepare CSV Source Data Files

Prepare CSV Source Data Files

When CSV is selected as the Source Platform, Next-Cart reads Product data from products.csv through File Upload. This Source option is handled through Custom Service. The included CSV file workflow migrates Products only unless additional entity handling has been explicitly approved and developed for the project.

Use the field names, field order, and row structure defined below. Change the Product values without changing the structure that Next-Cart uses to recognize records.

An accepted upload can still produce 0/0

File acceptance confirms that the file was uploaded. It does not confirm that Product records were recognized. If the CSV structure does not match the required format, migration processing can still run while Product progress remains 0/0, meaning 0 Source records were scanned and 0 records were migrated to the Target Platform.

File scope

The CSV file structure below covers Products. Additional CSV files do not add Customers, Orders, or other entity types unless that handling has been explicitly included in the approved Custom Service scope and developed for the migration.

If the project requires additional entity types, non-standard fields, relationship reconstruction, or other custom logic, define those requirements before execution. Use Prepare Custom Service Requirements to document the additional work.

Download the sample file

Use the CSV Product sample as the starting structure. Replace all sample records with your own Product data, preserve the structure below, and save the upload as products.csv.

Required CSV structure

Requirement	Required format
Source Platform	CSV
Migration Service	Custom Service
Included file scope	Products
Connection method	File Upload
Filename	products.csv
Encoding	UTF-8
Record layout	One header row followed by one Product or Product-variant record per row
Columns	43, in the required order

The first row must contain these headers in this order:

product_id,sku,price,status,weight,length,width,height,manage_stock,qty,name,description,short_description,barcode,manufacturer,categories,images,option_name_1,option_value_1,option_name_2,option_value_2,option_name_3,option_value_3,attribute_name_1,attribute_value_1,attribute_name_2,attribute_value_2,attribute_name_3,attribute_value_3,attribute_name_4,attribute_value_4,attribute_name_5,attribute_value_5,attribute_name_6,attribute_value_6,attribute_name_7,attribute_value_7,attribute_name_8,attribute_value_8,attribute_name_9,attribute_value_9,created_at,updated_at

Do not rename, remove, add, or reorder columns. When a field has no value for a record, leave the field empty and keep the column in place.

Supported Product fields

Field group	Fields
Product identity, pricing, status, dimensions, stock, and content	product_id, sku, price, status, weight, length, width, height, manage_stock, qty, name, description, short_description, barcode, manufacturer, categories, images
Product options	option_name_1, option_value_1, option_name_2, option_value_2, option_name_3, option_value_3
Product attributes	attribute_name_1 through attribute_name_9, paired with attribute_value_1 through attribute_value_9
Timestamps	created_at, updated_at

Format Product records

• Use one row for each Product or Product-variant record.
• Variants of the same Product can use the same product_id with different sku and option values.
• Keep every option name/value pair aligned by suffix, such as option_name_1 with option_value_1.
• Keep every attribute name/value pair aligned in the same way. Leave unused pairs empty instead of deleting their columns.
• In categories, separate multiple category entries with commas and use > for a hierarchy, such as Mobile > Phones.
• In images, separate multiple image URLs with commas.
• Because CSV uses commas as delimiters, enclose any value containing commas in double quotes so the value remains in one field.
• Use numeric 0 or 1 values for status and manage_stock rather than text labels.
• Use YYYY-MM-DD HH:MM:SS for created_at and updated_at when timestamps are provided.

Prepare the file

1. Create or open products.csv.
2. Place the required 43-field header on the first row in the exact order shown above.
3. Enter one Product or Product-variant record per row.
4. Keep unused fields empty without removing columns.
5. Check comma-containing values, including category lists, image lists, and descriptions, and quote them where required by CSV syntax.
6. Save the file as UTF-8 comma-delimited CSV with the filename products.csv.
7. Reopen the file and confirm that every record still contains 43 fields aligned to the header.

Verify before upload

Check	Pass condition
Filename	products.csv
Header	All 43 field names are present in the required order.
Record structure	Every Product or variant occupies one row under the same header.
Empty values	Empty data does not remove or shift a column.
CSV quoting	Values containing commas remain a single field.
Options and attributes	Each numbered name/value pair remains aligned.
Timestamps	Supplied timestamps use YYYY-MM-DD HH:MM:SS.

Store identity for file-based migrations

CSV does not require a Source Store URL. For a paid migration, the Target URL therefore locks when the Target setup provides one, Connect Stores is saved, and the migration advances to Configuration. Later migration activity can use another valid products.csv file, including one prepared from a different originating store, but it cannot replace a locked Target Store.

See Store URL Locking and Store Identity for the complete rule.

If Product progress is 0/0

A 0/0 Product result means Next-Cart did not recognize Product records from the uploaded CSV structure.

Check the filename, header names, column order, delimiter, quoting, and row alignment. Correct the file and upload it again. If all structural checks pass but Product progress remains 0/0, use Troubleshoot Connection Setup and provide the filename, a privacy-safe example row, and the migration result.

File Upload is migration input, not recurring synchronization

Selecting CSV provides a file-based Source for a migration. It does not create a recurring synchronization feed between the file and the Target Store. The included standard CSV workflow recognizes Products from products.csv when the required Next-Cart structure is used.

If the project needs scheduled imports, repeated external-feed processing, Customers, Orders, another data type, non-standard relationships, or business logic beyond the standard Product file structure, define that requirement through Custom Service.

Next Steps

Continue with Upload Source Data Files to prepare and validate the exported files for the Source connection.