Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Updated product imports user documentation (#13283)

jaburghesf15fd7e0eee6
diff --git a/docs/docs.json b/docs/docs.json
index a986f2eed8..64fa42ba98 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -916,6 +916,8 @@
"user/manage-products/search-products",
"user/manage-products/bulk-product-operations",
"user/manage-products/export-products",
+ "user/manage-products/import-products",
+ "user/manage-products/product-import-file-template",
"user/manage-products/stock-levels",
"user/manage-products/stock-transfers",
"user/manage-products/product-taxonomies",
diff --git a/docs/downloads/product_import_file_template.csv b/docs/downloads/product_import_file_template.csv
new file mode 100644
index 0000000000..5416aad5f4
--- /dev/null
+++ b/docs/downloads/product_import_file_template.csv
@@ -0,0 +1,45 @@
+product_id,sku,name,slug,status,description,meta_title,meta_description,meta_keywords,tags,price,compare_at_price,currency,width,height,depth,dimensions_unit,weight,weight_unit,available_on,discontinue_on,track_inventory,inventory_count,inventory_backorderable,tax_category,shipping_category,image1_src,image2_src,image3_src,option1_name,option1_value,option2_name,option2_value,option3_name,option3_value,category1,category2,category3,metafield.custom.fit,metafield.custom.material
+1,ABC-1,Active,active,active,An active product,Active Product,A Active Product,"active, single","active, single",10,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,,,,,,,Categories -> Taxon1,Categories -> Taxon2,Categories -> Taxon3 -> Subtaxon,Standard,Cotton
+2,ABC-2,No Inventory Tracking,no-inventory-tracking,draft,A product with no inventory tracking,No Tracking Product,A No Tracking Product,"no inv tracking, single","no inv tracking, single",15,0,USD,2,2,2,in,2,lb,,,FALSE,0,FALSE,Default,Default,,,,,,,,,,Categories -> Taxon1,Categories -> Taxon2,Categories -> Taxon3 -> Subtaxon,Standard,Cotton
+3,ABC-3,Backorderable,backorderable,draft,A backorderable product,Backorderable Product,A Backorderable Product,"backorderable, single","backorderable, single",20,0,USD,2,2,2,in,2,lb,,,TRUE,2000,TRUE,Default,Default,,,,,,,,,,Categories -> Taxon1,Categories -> Taxon2,Categories -> Taxon3 -> Subtaxon,Standard,Cotton
+4,ABC-4,Non-Taxable,non-taxable,draft,A non-taxable product,Non-Taxable Product,A Non-Taxable Product,"non-taxable, single","non-taxable, single",30,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Non-taxable,Default,,,,,,,,,,Categories -> Taxon4,,,Standard,Cotton
+5,ABC-5,Digital,digital,draft,A digital product,Digital Product,A Digital Product,"digital, single","digital, single",40,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Digital,,,,,,,,,,Categories -> Taxon1,Categories -> Taxon2,Categories -> Taxon3 -> Subtaxon,,
+18,ABC-18,Marked Down,compare-at,draft,A product with a compare at price,Compare At Product,A Compare At Product,"compare at, single","compare at, single",100,120,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,,,,,,,Categories -> Taxon1,Categories -> Taxon2,Categories -> Taxon3 -> Subtaxon,Standard,Cotton
+11,ABC-11,Multi-Variant Active,mv-active,active,An active multi-variant product,MV Active Product,A MV Active Product,"active, multi","active, multi",0,0,USD,2,3,2,in,2,lb,,,TRUE,0,FALSE,Default,Default,,,,,,,,,,Categories -> Taxon1,Categories -> Taxon2,Categories -> Taxon3 -> Subtaxon,Standard,Cotton
+11,ABC-11-1,,mv-active,,,,,,,19.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,White,Size,S,,,,,,,
+11,ABC-11-2,,mv-active,,,,,,,19.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,White,Size,M,,,,,,,
+11,ABC-11-3,,mv-active,,,,,,,19.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,White,Size,L,,,,,,,
+12,ABC-12,Multi-Variant No Inventory Tracking,mv-no-inv-tracking,draft,A multi-variant product with no inv tracking,MV No Inv Product,A MV No Inv Product,"no inv tracking, multi","no inv tracking, multi",0,0,USD,2,3,2,in,2,lb,,,FALSE,0,FALSE,Default,Default,,,,,,,,,,Categories -> Taxon1,Categories -> Taxon2,Categories -> Taxon3 -> Subtaxon,Standard,Cotton
+12,ABC-12-1,,mv-no-inv-tracking,,,,,,,29.99,0,USD,2,2,2,in,2,lb,,,FALSE,0,FALSE,Default,Default,,,,Color,Khaki,Size,S,,,,,,,
+12,ABC-12-2,,mv-no-inv-tracking,,,,,,,29.99,0,USD,2,2,2,in,2,lb,,,FALSE,0,FALSE,Default,Default,,,,Color,Khaki,Size,M,,,,,,,
+12,ABC-12-3,,mv-no-inv-tracking,,,,,,,29.99,0,USD,2,2,2,in,2,lb,,,FALSE,0,FALSE,Default,Default,,,,Color,Khaki,Size,L,,,,,,,
+13,ABC-13,Multi-Variant Backorderable,mv-backorderable,draft,An backorderable multi-variant product,MV Backorderable Product,A MV Backorderable Product,"backorderable, multi","backorderable, multi",0,0,USD,2,3,2,in,2,lb,,,TRUE,0,TRUE,Default,Default,,,,,,,,,,Categories -> Taxon1,Categories -> Taxon2,Categories -> Taxon3 -> Subtaxon,Standard,Cotton
+13,ABC-13-1,,mv-backorderable,,,,,,,39.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,TRUE,Default,Default,,,,Color,Blue,Size,S,,,,,,,
+13,ABC-13-2,,mv-backorderable,,,,,,,39.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,TRUE,Default,Default,,,,Color,Blue,Size,M,,,,,,,
+13,ABC-13-3,,mv-backorderable,,,,,,,39.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,TRUE,Default,Default,,,,Color,Blue,Size,L,,,,,,,
+14,ABC-14,Multi-Variant Non-Taxable,mv-non-taxable,draft,An non-taxable multi-variant product,MV Non-Taxable Product,A MV Non-Taxable Product,"non-taxable, multi","non-taxable, multi",0,0,USD,2,3,2,in,2,lb,,,TRUE,0,FALSE,Non-taxable,Default,,,,,,,,,,Categories -> Taxon1,Categories -> Taxon2,Categories -> Taxon3 -> Subtaxon,Standard,Cotton
+14,ABC-14-1,,mv-non-taxable,,,,,,,49.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Non-taxable,Default,,,,Color,Black,Size,S,,,,,,,
+14,ABC-14-2,,mv-non-taxable,,,,,,,49.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Non-taxable,Default,,,,Color,Black,Size,M,,,,,,,
+14,ABC-14-3,,mv-non-taxable,,,,,,,49.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Non-taxable,Default,,,,Color,Black,Size,L,,,,,,,
+15,ABC-15,Multi-Variant Digital,mv-digital,draft,An digital multi-variant product,MV Digital Product,A MV Digital Product,"digital, multi","digital, multi",0,0,USD,2,3,2,in,2,lb,,,TRUE,0,FALSE,Default,Digital,,,,,,,,,,Categories -> Taxon4,,,,
+15,ABC-15-1,,mv-digital,,,,,,,59.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Digital,,,,Level,Beginner,,,,,,,,,
+15,ABC-15-2,,mv-digital,,,,,,,59.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Digital,,,,Level,Intermediate,,,,,,,,,
+15,ABC-15-3,,mv-digital,,,,,,,59.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Digital,,,,Level,Advanced,,,,,,,,,
+19,ABC-19,Multi-Variant Marked Down,mv-compare-at-price,draft,An multi-variant product with compare at price,MV Compare At Product,A MV Compare At Product,"compare at, multi","compare at, multi",0,0,USD,2,3,2,in,2,lb,,,TRUE,0,FALSE,Default,Default,,,,,,,,,,Categories -> Taxon1,Categories -> Taxon2,Categories -> Taxon3 -> Subtaxon,Standard,Cotton
+19,ABC-19-1,,mv-compare-at-price,,,,,,,89.99,99.99,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,Orange,Size,S,,,,,,,
+19,ABC-19-2,,mv-compare-at-price,,,,,,,89.99,99.99,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,Orange,Size,M,,,,,,,
+19,ABC-19-3,,mv-compare-at-price,,,,,,,89.99,99.99,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,Orange,Size,L,,,,,,,
+22,ABC-22,Multi-Variant Three Options,mv-three-options,draft,An multi-variant product with three options,,,,,0,0,USD,2,3,2,in,2,lb,,,TRUE,0,FALSE,Default,Default,,,,,,,,,,Categories -> Taxon1,Categories -> Taxon2,Categories -> Taxon3 -> Subtaxon,Standard,Cotton
+22,ABC-22-1,,mv-three-options,,,,,,,99.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,White,Size,XS,Fit,Tight,,,,,
+22,ABC-22-2,,mv-three-options,,,,,,,99.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,White,Size,S,Fit,Tight,,,,,
+22,ABC-22-3,,mv-three-options,,,,,,,99.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,White,Size,M,Fit,Tight,,,,,
+22,ABC-22-4,,mv-three-options,,,,,,,99.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,White,Size,XS,Fit,Loose,,,,,
+22,ABC-22-5,,mv-three-options,,,,,,,99.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,White,Size,S,Fit,Loose,,,,,
+22,ABC-22-6,,mv-three-options,,,,,,,99.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,White,Size,M,Fit,Loose,,,,,
+22,ABC-22-7,,mv-three-options,,,,,,,99.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,Black,Size,XS,Fit,Tight,,,,,
+22,ABC-22-8,,mv-three-options,,,,,,,99.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,Black,Size,S,Fit,Tight,,,,,
+22,ABC-22-9,,mv-three-options,,,,,,,99.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,Black,Size,M,Fit,Tight,,,,,
+22,ABC-22-10,,mv-three-options,,,,,,,99.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,Black,Size,XS,Fit,Loose,,,,,
+22,ABC-22-11,,mv-three-options,,,,,,,99.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,Black,Size,S,Fit,Loose,,,,,
+22,ABC-22-12,,mv-three-options,,,,,,,99.99,0,USD,2,2,2,in,2,lb,,,TRUE,2000,FALSE,Default,Default,,,,Color,Black,Size,M,Fit,Loose,,,,,
+
diff --git a/docs/images/user/products/import-products/1-products-tab.png b/docs/images/user/products/import-products/1-products-tab.png
new file mode 100644
index 0000000000..f7b1058275
Binary files /dev/null and b/docs/images/user/products/import-products/1-products-tab.png differ
diff --git a/docs/images/user/products/import-products/2-click-import.png b/docs/images/user/products/import-products/2-click-import.png
new file mode 100644
index 0000000000..084f99e214
Binary files /dev/null and b/docs/images/user/products/import-products/2-click-import.png differ
diff --git a/docs/images/user/products/import-products/3-upload-file.png b/docs/images/user/products/import-products/3-upload-file.png
new file mode 100644
index 0000000000..adee450b91
Binary files /dev/null and b/docs/images/user/products/import-products/3-upload-file.png differ
diff --git a/docs/images/user/products/import-products/4-upload-complete.png b/docs/images/user/products/import-products/4-upload-complete.png
new file mode 100644
index 0000000000..373979e4c8
Binary files /dev/null and b/docs/images/user/products/import-products/4-upload-complete.png differ
diff --git a/docs/images/user/products/import-products/5-delimiter.png b/docs/images/user/products/import-products/5-delimiter.png
new file mode 100644
index 0000000000..8d90b54639
Binary files /dev/null and b/docs/images/user/products/import-products/5-delimiter.png differ
diff --git a/docs/images/user/products/import-products/6-map-fields.png b/docs/images/user/products/import-products/6-map-fields.png
new file mode 100644
index 0000000000..f3cb26bc00
Binary files /dev/null and b/docs/images/user/products/import-products/6-map-fields.png differ
diff --git a/docs/images/user/products/import-products/7-import-processing.png b/docs/images/user/products/import-products/7-import-processing.png
new file mode 100644
index 0000000000..0a9a16d48a
Binary files /dev/null and b/docs/images/user/products/import-products/7-import-processing.png differ
diff --git a/docs/user/manage-products/import-products.mdx b/docs/user/manage-products/import-products.mdx
index ddaa685893..8dd2b245f6 100644
--- a/docs/user/manage-products/import-products.mdx
+++ b/docs/user/manage-products/import-products.mdx
@@ -1,102 +1,83 @@
---
title: "Import Products"
-description: "How to import products in the Spree open-source eCommerce dashboard"
+description: "How to import products files in the Spree Commerce dashboard."
---
-Adding products one at a time can be very time consuming, especially if you have hundreds or even thousands of products to upload.
+Adding products one at a time can be time consuming - especially when you're dealing with hundreds or thousands of SKUs. 
-You can save a lot of that time by making use of the product import feature which allows you to upload products in bulk from a CSV or Excel file.
+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.
-<Note>It’s strongly recommended that you pre-format your product file so that the columns match the internal values in Spree. To learn more about formatting your product files, please refer to a separate support article.</Note>
+Need an example? Please refer to [<u>Product Import File Template</u>](https://spreecommerce.org/docs/user/manage-products/product-import-file-template) to download a template and see a list of internal fields.
-To import a product file, navigate to the Products tab of the admin dashboard and locate the ‘Import’ button in the top right corner.
+<Note>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).</Note>
-<img alt="Products Tab" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926795/docs/Manage%20Products/Import%20Products/2.2.3.1.1_Product_Imports_-_Products_Tab_g67bxn.png" />
+## How to Import Products
-Clicking on ‘Import’ will open up a window to begin the process of importing a product file.
+To get started, navigate to the Products tab of the admin dashboard.
-<img alt="Product Import Window" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926797/docs/Manage%20Products/Import%20Products/2.2.3.1.2_Product_Imports_-_Import_Window_m9syrc.png" />
+![Spree Commerce products tab](/docs/images/user/products/import-products/1-products-tab.png)
-You’ll be greeted by two options:
+Click **Import**  in the top right corner. This will open a side panel where you can begin the import process.
-1. Upload file - choose an existing file to automatically import to your store
+![Spree product importer](/docs/images/user/products/import-products/2-click-import.png)
-2. Manually enter data - create a file by entering all the necessary product data manually
+From here, simply follow these steps to import your product catalog:
-First, lets take a look at uploading a file
+### Step 1: Upload a Product File
-## Upload File
+![Uploading a product file to Spree](/docs/images/user/products/import-products/3-upload-file.png)
-When clicking on ‘Upload file’, you’ll be prompted to select a file from your device.
+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**.
-Select the file you want to upload and click Open.
+<Note>The importer supports both single and multi-variant products - just follow the multi-variant format in the [<u>Product File Import Template</u>](https://spreecommerce.org/docs/user/manage-products/product-import-file-template).</Note>
-<img alt="Choose A Product File" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926796/docs/Manage%20Products/Import%20Products/2.2.3.1.3_Product_Imports_-_Choose_A_File_pse9jm.png" />
+If successful, the UI will indicate that the upload was completed:
-This will automatically extract the product data from the file.
+![Successfully uploaded product file](/docs/images/user/products/import-products/4-upload-complete.png)
-### Map Fields
+<Note>Double-check for any formatting issues, data type mismatches, and duplicates before uploading.</Note>
-Next, you’ll be directed to the field mapping step, which allows you to match the incoming fields from the CSV with the internal fields in your store.
+#### Select a Delimiter
-<img alt="Map Imported Product Fields" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926794/docs/Manage%20Products/Import%20Products/2.2.3.1.4_Product_Imports_-_Map_Fields_autpcg.png" />
+![Spree CSV importer delimiter](/docs/images/user/products/import-products/5-delimiter.png)
-Hovering over the rows with the cursor will show a preview of the incoming data.
+Before processing the file, you need to select which delimiter separates values in your file:
-<img alt="Imported Field Previews" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926796/docs/Manage%20Products/Import%20Products/2.2.3.1.5_Product_Imports_-_Field_Previews_x2kg27.png" />
+- , (comma) - most common for CSVs
+- | (pipe)
+- ; (semicolon)
+- \\t (tab)
-In the ‘Destination Fields’ column, you can select the internal field that the incoming field should be mapped to.
+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.
-<Note> If you preformatted your CSV file to match the internal naming conventions, most if not all of these fields will be automatically matched.</Note>
+### Step 2: Map Fields and Submit
-<img alt="Import Destination Fields" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926795/docs/Manage%20Products/Import%20Products/2.2.3.1.6_Product_Imports_-_Destination_Fields_ef25ee.png" />
+![Mapping fields in the Spree product importer](/docs/images/user/products/import-products/6-map-fields.png)
-Once you’re happy with the mapping of the fields, click ‘Continue’ in the top right corner of the window.
+With the file uploaded, you’ll now be prompted to map your file’s columns to Spree’s internal fields.
-### Review and Submit
+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.
-On the next screen, can review the data to be uploaded and submit it for upload provided there are no errors.
+Once satisfied, click **Continue** in the bottom-right corner to submit the file for import.
-<img alt="Import Review Step" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926799/docs/Manage%20Products/Import%20Products/2.2.3.1.7_Product_Imports_-_Review_Step_yoru5g.png" />
+### Step 3: Monitor Import Status
-In the above example, there are some errors - two rows have a matching SKU.
+![Spree CSV importer processing product rows](/docs/images/user/products/import-products/7-import-processing.png)
-To fix this error, you can simply click on one of the fields and edit the data and click Enter.
+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 
-<Note> You can edit all of the other data fields in the file, error or not, in the same manner.</Note>
+<Note>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.</Note>
-<img alt="Fix Product Import Errors" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926798/docs/Manage%20Products/Import%20Products/2.2.3.1.8_Product_Imports_-_Fix_Errors_nncqes.png" />
+## Update Products in Bulk
-Once you’ve fixed all the errors and updated any other fields you want to change, click Submit Data in the top right corner of the window.
+You can also use the product importer to update existing products in your catalog.
-<img alt="Submit Product Import Data" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926795/docs/Manage%20Products/Import%20Products/2.2.3.1.9_Product_Imports_-_Submit_Data_s9n9fh.png" />
+To do so:
-### Import Processing
+1. [<u>Export your product catalog</u>](https://spreecommerce.org/docs/user/manage-products/export-products) from the Products tab
+2. Make any necessary changes directly in the file
+3. Re-import the updated file through the product importer
-Once you’ve submitted the data, you’ll be redirected to another page where you can watch the monitor the progress of the import process.
+<Warning>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.</Warning>
-<img alt="Product Import Processing" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926801/docs/Manage%20Products/Import%20Products/2.2.3.1.10_Product_Imports_-_Import_Processing_sx7rzx.png" />
-
-When the import is complete, the status of the import at the top of the page will be marked as ‘Processed’.
-
-<img alt="Product Import Processed" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926795/docs/Manage%20Products/Import%20Products/2.2.3.1.11_Product_Imports_-_Import_Processed_ffowr9.png" />
-
-The products will now manageable in the Products tab of the admin dashboard.
-
-<img alt="Products Uploaded" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926800/docs/Manage%20Products/Import%20Products/2.2.3.1.12_Product_Imports_-_Products_Uploaded_b5ucnj.png" />
-
-## Manually Enter Data
-
-If you don’t have an existing file to upload, you can manually enter the product data directly into the product importer, which you may find more convenient than adding products one by one using the product editor.
-
-Simply fill in all of the necessary fields following the Product File Format guidelines.
-
-<img alt="Manually Enter Data" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926796/docs/Manage%20Products/Import%20Products/2.2.3.1.13_Product_Imports_-_Manually_Enter_Data_dd3xxa.png" />
-
-Once you’ve added all the relevant product data, click ‘Submit data’ in the top right corner of the window and the products will be imported.
-
-## Import Auditing
-
-You can audit past imports by navigating to Settings > Audit Trail and clicking on ‘Imports’ at the top of the page.
-
-<img alt="Audit Product Imports" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1733926799/docs/Manage%20Products/Import%20Products/2.2.3.1.14_Product_Imports_-_Audit_Imports_eof5xv.png" />
\ No newline at end of file
+This is the safest and most efficient way to make large-scale updates to product data such as pricing, descriptions, inventory, or metafields.
diff --git a/docs/user/manage-products/product-import-file-template.mdx b/docs/user/manage-products/product-import-file-template.mdx
index af2b9b9c0e..e4daa4046f 100644
--- a/docs/user/manage-products/product-import-file-template.mdx
+++ b/docs/user/manage-products/product-import-file-template.mdx
@@ -1,45 +1,53 @@
---
title: "Import File Template"
-description: "This is a product import file template for Spree Commerce open-source"
+description: "Download a product import file template for Spree Commerce open-source"
---
-Below is a list of all the product fields that can be added to your product files.
+Below is a list of all the product fields that can be imported via CSV (required fields in bold).
-For example values, please refer to this [product import template file](https://vendo-production-res.cloudinary.com/raw/upload/v1734435134/docs/Manage%20Products/Import%20Products/Product_Import_File_Template_zp33fj.csv).
+For an example of **how to structure multi-variant products**, please download this [product import file template](https://raw.githubusercontent.com/spree/spree/refs/heads/main/docs/downloads/product_import_file_template.csv).
-| Field | Description |
+<Note>You don’t need to follow the field naming conventions in this template exactly. Field names can be mapped manually during the import process.</Note>
+
+<Warning>The **slug** field acts as the unique identifier for the product in Spree - no two products can share the same slug. When updating products via CSV import, the slug must exactly match an existing record to avoid creating duplicates.</Warning>
+
+| Field | Description |
| ----------------------- | ------------------------------------------------------------------------------------------- |
-| Product Identifier | Unique values autogenerated when creating products, but needs a placeholder when importing. |
-| SKU | The name of the product |
-| Name | Reported age |
-| Category #1 | The 1st category the product should be assigned to |
-| Category #N | The Nth category the product should be assigned to |
-| Description | The product description |
-| Image URL | A link to the product image |
-| Price | The the price of the product to be paid by the customer |
-| Compare at price | The non-marked-down price of the product being sold |
-| Inventory count | The quantity of the product in stock |
-| Track Inventory | Whether or not you track inventory levels for the product |
-| Inventory Backorderable | Whether or not the product is backorderable when out of stock |
-| SEO Title | If not set, Name will be used in search engine listings |
-| SEO Description | If not set, Description will be used in search engine listings |
-| SEO Keywords | Can improve your website's visibility, attract more relevant traffic |
-| Option #1 name | The name of the 1st option the product is available in |
-| Option #1 value | The value of the 1st option the product is available in |
-| Option #N name | The name of the Nth option the product is available in |
-| Option #N value | The value of the Nth option the product is available in |
-| Property #1 name | The name of the 1st property associated with the product |
-| Property #1 value | The value of the 1st property associated with the product |
-| Property #N name | The name of the Nth property associated with the product |
-| Property #N value | The value of the Nth property associated with the product |
-| Tags | Tags that should be added to the product |
-| Width | Width of the product or package |
-| Height | Height of the product or package |
-| Depth | Depth of the product or package |
-| Weight | Weight of the product or package |
-| Available on | When the product should be made available for purchase |
-| Discontinue on | When the product should be discontinue and hidden from the storefront |
-| Status | The status of the product, e.g., Active, Draft, Archived |
-| Slug | The URL of the product |
-| Tax Category | The tax category the product falls in to |
-| Digital | Whether or not the product is a digital product, i.e., shipping required or not required |
\ No newline at end of file
+| **sku** | A unique alphanumeric code used to identify variants |
+| **name** | The name of the product |
+| **slug** | Sets the URL path of the product (e.g. yourstore.com/products/slug) |
+| status | The status of the product, e.g., Active, Draft, Archived |
+| description | The product description |
+| meta_title | If not set, Name will be used in search engine listings |
+| meta_description | If not set, Description will be used in search engine listings |
+| meta_keywords | Can improve your website's visibility, attract more relevant traffic |
+| tags | Tags that should be added to the product |
+| price | The price for the product/variant to be paid by the customer |
+| compare_at_price | The non-marked-down price of the product being sold |
+| currency | The currency in which the price should be imported |
+| width | Width of the product/variant |
+| height | Height of the product/variant |
+| depth | Depth of the product/variant |
+| dimensions_unit | The unit of measurement used for the dimensions (in, ft, cm, mm) |
+| weight | Weight of the product/variant |
+| weight_unit | The unit of measurement used for weight (oz, lbs, g, kg) |
+| available_on | When the product should be made available for purchase |
+| discontinue_on | When the product should be discontinued and hidden from the storefront |
+| track_inventory | Whether or not you track inventory levels for the product (TRUE/FALSE) |
+| inventory_count | The stock quantity of the product/variant |
+| inventory_backorderable | Whether the product can be ordered when out of stock |
+| tax_category | The tax category the product should be assigned, e.g., Default, Non-taxable |
+| shipping_category | The shipping category the product should be assigned, e.g., Default, Digital |
+| image1_src | A link to the primary image product/variant image |
+| image2_src | A link to the second product/variant image |
+| image3_src | A link to the third product/variant image |
+| option1_name | The name of the 1st [product option](https://spreecommerce.org/docs/user/manage-products/product-options)|
+| option1_value | The value of the 1st product option |
+| option2_name | The name of the 2nd product option |
+| option2_value | The value of the 2nd product option |
+| option3_name | The name of the 3rd product option |
+| option3_value | The value of the 3rd product option |
+| category1 | The 1st [category](https://spreecommerce.org/docs/user/manage-products/product-taxonomies) to which the product should be assigned|
+| category2 | The 2nd category to which the product should be assigned |
+| category3 | The 3rd category to which the product should be assigned |
+| metafield.namespace.key | The value for the product metafield [namespace.key](https://spreecommerce.org/docs/user/settings/metafields)|
diff --git a/docs/user/settings/metafields.mdx b/docs/user/settings/metafields.mdx
index 4e013f35a0..aa63b7f40f 100644
--- a/docs/user/settings/metafields.mdx
+++ b/docs/user/settings/metafields.mdx
@@ -46,7 +46,7 @@ You can define metafields for nearly any data object in Spree:
- **Image** - e.g., display priority or alt tag
- **Line Item** - e.g., engraving or personalization notes
- **Newsletter Subscriber** - e.g., subscription source
-- **Option Type**
+- **Option Type** - e.g., an extended description for color choices
- **Option Value** - e.g., color hex code
- **Order** - e.g., internal comment, PO number
- **Payment** - e.g., external transaction reference