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:

​
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:
  • 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:
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:

​
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.