Skip to main content

Documentation Index

Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt

Use this file to discover all available pages before exploring further.

Adding products one at a time can be time consuming - especially when you’re dealing with hundreds or thousands of SKUs.  Spree’s CSV importer allows you to upload products in bulk using a pre-formatted CSV file, dramatically reducing the time required to launch or scale your catalog. Need an example? Please refer to Product Import File Template to download a template and see a list of internal fields.
Your product file does not need to exactly match the import template. Thanks to the field mapping step, you can manually match each column to the appropriate internal field during import (see Step 2 below).

​
How to Import Products

To get started, navigate to the Products tab of the admin dashboard. Spree Commerce products tab Click Import  in the top right corner. This will open a side panel where you can begin the import process. Spree product importer From here, simply follow these steps to import your product catalog:

​
Step 1: Upload a Product File

Uploading a product file to Spree First, you’ll need to upload the file you wish to import. Either drag-and-drop the file into the box or select a file from your computer by clicking browse files.
The importer supports both single and multi-variant products - just follow the multi-variant format in the Product File Import Template.
If successful, the UI will indicate that the upload was completed: Successfully uploaded product file
Double-check for any formatting issues, data type mismatches, and duplicates before uploading.

​
Select a Delimiter

Spree CSV importer delimiter Before processing the file, you need to select which delimiter separates values in your file:
  • , (comma) - most common for CSVs
  • | (pipe)
  • ; (semicolon)
  • \t (tab)
Once the file has been uploaded and the correct delimiter has been selected, click Create at the bottom of the side panel to continue to Step 2.

​
Step 2: Map Fields and Submit

Mapping fields in the Spree product importer With the file uploaded, you’ll now be prompted to map your file’s columns to Spree’s internal fields. Spree will try to match fields automatically when names are identical (or very similar), but you can manually select destination fields from the dropdowns on the right-hand side column for any unmatched, or incorrectly mapped fields. Once satisfied, click Continue in the bottom-right corner to submit the file for import.

​
Step 3: Monitor Import Status

Spree CSV importer processing product rows After submitting the file, you’ll be redirected to a processing screen where you can monitor the progress of the import. All that’s left to do is wait until the import has finished processing 
If there are any errors in your file (e.g., missing fields, duplicate values), the processing screen will indicate the error with an error message on the affected row.

​
Update Products in Bulk

You can also use the product importer to update existing products in your catalog. To do so:
  1. Export your product catalog from the Products tab
  2. Make any necessary changes directly in the file
  3. Re-import the updated file through the product importer
When updating products in bulk, make sure to keep the slug exactly the same for each existing product. The slug is the unique identifier used during import - changing it will cause Spree to treat the row as a new product and create a duplicate record.
This is the safest and most efficient way to make large-scale updates to product data such as pricing, descriptions, inventory, or metafields.
If your store sells in multiple currencies, your exported file will include additional price-only rows for each currency. See Multi-Currency Import/Export for details on how these rows work.