Skip to main content

​
Overview

Spree Commerce provides a built-in CSV import system that makes migrating from Shopify straightforward. Since Shopify exports data in CSV format and Spree supports flexible column mapping, you can import your products and customers with minimal manual transformation. This guide covers:
  • Exporting data from Shopify
  • Preparing CSV files for Spree
  • Importing products (with variants, images, and categories)
  • Importing customers (with addresses)
  • Post-migration checklist

​
Exporting Data from Shopify

​
Products

  1. In your Shopify admin, go to Products
  2. Click Export and choose All products (or a filtered selection)
  3. Select Plain CSV file format
  4. Download the file

​
Customers

  1. In your Shopify admin, go to Customers
  2. Click Export and choose All customers
  3. Select Plain CSV file format
  4. Download the file

​
Products Migration

​
Column Mapping

Spree’s import system lets you map CSV columns to Spree fields during the import process. Here’s how Shopify columns map to Spree fields:
Shopify ColumnSpree FieldNotes
HandleslugRequired. URL-friendly product identifier
Variant SKUskuRequired. Stock keeping unit
TitlenameRequired. Product name
Variant PricepriceRequired. No currency symbols
Statusstatusactive, draft, or archived
Body (HTML)descriptionHTML description is supported
SEO Titlemeta_titleMeta title for SEO
SEO Descriptionmeta_descriptionMeta description for SEO
TagstagsComma-separated tags
Variant Compare At Pricecompare_at_priceOriginal price for sale display
Variant GramsweightSee weight conversion note below
Variant Weight Unitweight_unitg, kg, lb, or oz
Image Srcimage1_srcProduct image URL
Option1 Nameoption1_namee.g., Size, Color
Option1 Valueoption1_valuee.g., Small, Red
Option2 Nameoption2_nameSecond option name
Option2 Valueoption2_valueSecond option value
Option3 Nameoption3_nameThird option name
Option3 Valueoption3_valueThird option value
Cost per item—Not directly imported, can be set via metafields
Vendor—Can be imported as a metafield or tag
Product Categorycategory1Requires format adjustment (see below)

​
Step-by-Step Import

1

Upload the CSV

In Spree Admin, go to Products → Import and upload your Shopify products CSV file.
2

Map the columns

Spree will auto-detect columns where names are similar. For Shopify-specific columns, you’ll need to manually map them:
  • Map Handle → slug
  • Map Title → name
  • Map Variant SKU → sku
  • Map Variant Price → price
  • Map Body (HTML) → description
  • Map Variant Compare At Price → compare_at_price
  • Map Image Src → image1_src
  • Map Variant Grams → weight
  • Map Variant Weight Unit → weight_unit
  • Map SEO Title → meta_title
  • Map SEO Description → meta_description
  • Map option and tag columns as needed
3

Review and start the import

Once all required fields are mapped, click Start Import. The import runs in the background and you can track progress in the admin.

​
Multi-Variant Products

Both Shopify and Spree handle multi-variant products the same way in CSV format — multiple rows share the same Handle/slug: 
Handle,Title,Variant SKU,Variant Price,Option1 Name,Option1 Value,Option2 Name,Option2 Value
my-tshirt,My T-Shirt,TSHIRT-001,29.99,,,
my-tshirt,My T-Shirt,TSHIRT-S-RED,29.99,Size,Small,Color,Red
my-tshirt,My T-Shirt,TSHIRT-M-RED,29.99,Size,Medium,Color,Red
my-tshirt,My T-Shirt,TSHIRT-L-RED,29.99,Size,Large,Color,Red
  • The first row (no option values) creates the product and master variant
  • Subsequent rows with the same Handle create additional variants
This format works directly with Spree’s importer — no transformation needed.

​
Handling Images

Shopify exports image URLs in the Image Src column. Map this to image1_src in Spree. The importer will download and attach images asynchronously from the provided URLs.
Shopify CDN URLs remain accessible after export, so images will download successfully. If you have multiple images per product, Spree supports image1_src, image2_src, and image3_src fields. For products with more than 3 images, you can add additional images manually after import.

​
Handling Categories

Shopify uses Product Category (their taxonomy) and Type (free-form). Spree uses a hierarchical taxonomy format with -> separators. To map Shopify categories to Spree, you may need to adjust the values in your CSV before import: 
# Shopify format
Product Category: Apparel & Accessories > Clothing > Shirts & Tops

# Spree format (use -> separator)
category1: Categories -> Clothing -> Shirts & Tops
You can either:
  1. Pre-process your CSV to convert the category format
  2. Create your taxonomy in Spree first, then use the category1, category2, and category3 fields during mapping

​
Weight Conversion

Shopify’s Variant Grams column is always in grams regardless of the Variant Weight Unit setting. When mapping to Spree:
  • Map Variant Grams → weight
  • Map Variant Weight Unit → weight_unit
  • If Variant Weight Unit is missing, the weight will be treated as grams

​
Columns You Can Skip

These Shopify-specific columns don’t have direct Spree equivalents and can be safely skipped:
  • Vendor — consider importing as a tag or metafield
  • Published — use status instead (active = published)
  • Variant Inventory Tracker — Spree handles inventory tracking differently
  • Variant Fulfillment Service — not applicable
  • Variant Requires Shipping — controlled by shipping categories in Spree
  • Variant Taxable — controlled by tax categories in Spree
  • Variant Barcode — can be added as a metafield
  • Gift Card — Spree has its own gift card system
  • Google Shopping / * — not imported (legacy Shopify columns)

​
Customers Migration

​
Column Mapping

Shopify’s customer CSV maps closely to Spree’s customer import schema:
Shopify ColumnSpree FieldNotes
EmailemailRequired. Customer email
First Namefirst_nameCustomer first name
Last Namelast_nameCustomer last name
PhonephonePrimary phone number
Accepts Email Marketingaccepts_email_marketingyes/no format works directly
TagstagsComma-separated tags
Default Address CompanycompanyCompany name
Default Address Address1address1Street address line 1
Default Address Address2address2Street address line 2
Default Address CitycityCity
Default Address Province Codeprovince_codeISO state/province code (e.g., NY, CA)
Default Address Country Codecountry_codeISO country code (e.g., US, GB)
Default Address ZipzipPostal/zip code
Note—Not directly imported, can be added as a metafield
Tax Exempt—Not directly imported
Total Spent—Read-only in Shopify, not imported
Total Orders—Read-only in Shopify, not imported

​
Step-by-Step Import

1

Upload the CSV

In Spree Admin, go to Customers → Import and upload your Shopify customers CSV file.
2

Map the columns

Map the Shopify columns to Spree fields. Most columns will auto-map since the field names are similar. You’ll need to manually map the address fields:
  • Map Default Address Company → company
  • Map Default Address Address1 → address1
  • Map Default Address Address2 → address2
  • Map Default Address City → city
  • Map Default Address Province Code → province_code
  • Map Default Address Country Code → country_code
  • Map Default Address Zip → zip
3

Review and start the import

Once all required fields are mapped, click Start Import. New customer accounts will be created with randomly generated passwords.
Imported customers will need to use the Forgot Password flow to set their password, as Shopify does not export passwords. Consider sending a welcome email to imported customers with a password reset link.

​
Customer Address Handling

Shopify only exports the default address in the customer CSV. The Spree importer creates this as both the billing and shipping address for each customer. If your customers have multiple addresses in Shopify, only the default will be migrated.

​
Post-Migration Checklist

After importing your data, review the following:
  • Verify product counts match between Shopify and Spree
  • Check that variants and options imported correctly
  • Confirm images downloaded successfully
  • Review category/taxonomy assignments
  • Set up tax categories and shipping categories if not mapped during import
  • Configure inventory tracking and stock levels
  • Review product statuses (active/draft/archived)
  • Verify customer counts match
  • Check that addresses imported correctly
  • Send password reset emails to imported customers
  • Verify email marketing opt-in status
These Shopify resources require additional migration steps:
  • Orders — Historical orders are not imported via CSV. Use the Spree API for programmatic order migration if needed
  • Discount codes / Promotions — Recreate manually in Spree Admin or via API
  • Collections — Set up as Taxons in Spree
  • Pages / Blog posts — Migrate content manually or via API
  • Gift cards — Recreate in Spree’s gift card system
  • Customer passwords — Shopify does not export passwords; customers must reset them

​
Troubleshooting

​
Common Issues

Import shows failed rows Check the import details page in the admin to see row-level errors. Common causes:
  • Missing required fields (slug, sku, name, price for products; email for customers)
  • Invalid price format (remove currency symbols)
  • Duplicate SKUs across products
Images not appearing Images are downloaded asynchronously after import. Allow some time for the background jobs to complete. If images still don’t appear, verify the URLs are accessible. Categories not created Ensure category values use the Taxonomy -> Taxon -> Child format with -> as the separator (spaces around the arrow). Special characters in CSV Ensure your CSV is UTF-8 encoded. If exported from Shopify as “CSV for Excel”, it may include a BOM (Byte Order Mark) which Spree handles correctly.