Learn the required fields, format specifications, and optimization strategies for Shopify Product CSV feeds.
A Shopify Product CSV is a structured spreadsheet file used to bulk import, export, and update product data in your Shopify online store. Shopify uses a specific CSV format where each row represents either a product or a product variant, with the first row containing predefined column headers. The CSV format allows merchants to manage large product catalogs efficiently, making it possible to create hundreds or thousands of products in a single upload rather than entering them one by one through the Shopify Admin interface. Each product in the CSV is defined by attributes including title, body HTML (description), vendor, product type, tags, variant details (price, SKU, inventory, weight), and image URLs. Understanding and optimizing this format is essential for any Shopify merchant managing a catalog of more than a handful of products.
Optimizing your Shopify Product CSV is essential for maintaining a well-organized store and ensuring a smooth customer experience. The quality of your product data directly impacts your store's search functionality, collection organization, SEO performance, and sales channel compatibility. Products with complete and well-structured data are easier to find through site search, display correctly in automated collections, and sync properly to sales channels like Google Shopping, Facebook, Instagram, and TikTok. The CSV format also serves as the foundation for migrating product data between e-commerce platforms, making it the standard interchange format for Shopify stores. Understanding and optimizing the CSV structure helps you avoid common import errors that can result in missing products, broken variant relationships, or incorrect pricing.
Shopify supports product CSV import and export through the Admin interface (Settings > Import/Export), the Shopify Admin API for programmatic access, and various third-party apps that extend the native CSV functionality. The native CSV import supports creating new products and updating existing ones by matching on the Handle field (URL slug). For variant-heavy products, the CSV format uses multiple rows per product, with the first row containing all product-level data and subsequent rows containing only variant-specific data. Shopify processes CSV imports asynchronously and sends an email notification upon completion, including a summary of any errors encountered. For stores with more than 50,000 products or complex variant structures, the Admin API (specifically the bulkOperationRunMutation GraphQL endpoint) provides more control and better error handling than CSV imports.
Required and optional fields for your product feed
Key structural rules and formatting requirements for this feed type
The Handle is the URL-friendly version of your product title and serves as the unique identifier that links multiple CSV rows belonging to the same product. The first row with a new Handle value creates the product and should contain all product-level data (Title, Body, Vendor, Tags, etc.). Subsequent rows with the same Handle are treated as additional variants or images for that product and should only contain variant-specific data. If you include product-level data on a variant row, it will be ignored. Handles must be lowercase and use hyphens instead of spaces.
Shopify supports up to three option dimensions per product (e.g., Size, Color, Material), defined using Option1 Name/Value, Option2 Name/Value, and Option3 Name/Value columns. The first row of a product should include the Option Names and the first variant's Option Values. Subsequent variant rows should leave the Option Names blank and only fill in the Option Values. Each unique combination of Option Values creates a separate variant with its own SKU, price, inventory, and barcode. Products with a single variant should use Title as the Option1 Name and Default Title as the Option1 Value.
Product images are specified using the Image Src column containing a publicly accessible URL to the image file. The Image Position column determines the display order (1 = primary image). To add multiple images to a single product, create additional rows with the same Handle and only fill in the Image Src, Image Position, and optionally Image Alt Text columns. Variant-specific images are linked using the Variant Image column. Shopify downloads images from the URLs during import, so they must be accessible at the time of upload. Supported formats are JPEG, PNG, GIF, and WebP with a maximum of 20MB per image.
The Body (HTML) column accepts HTML-formatted product descriptions. Use standard HTML tags like <p>, <ul>, <li>, <strong>, <em>, and <h2>-<h6> for structured content. Avoid inline styles and JavaScript. When the HTML contains commas or quotes, the entire cell must be wrapped in double quotes, with internal quotes escaped by doubling them. Keep descriptions between 300 and 1000 words for optimal SEO performance. Include relevant keywords naturally and structure the content with headings and bullet points for readability.
The Variant Inventory Tracker column specifies the inventory tracking service (shopify for Shopify's built-in tracking, or a third-party fulfillment service handle). The Variant Inventory Qty column sets the initial stock quantity. The Variant Inventory Policy determines behavior when inventory reaches zero: deny (stop selling) or continue (allow overselling for pre-orders or made-to-order). The Variant Fulfillment Service column specifies which fulfillment service handles the product (manual for self-fulfillment). These fields are critical for accurate inventory management and order processing.
Shopify CSV files must use UTF-8 encoding to properly handle special characters, accented letters, and international text. Use commas as column delimiters and enclose fields containing commas, line breaks, or double quotes in double quotes. When editing in spreadsheet applications, be careful that the application does not alter the encoding or add an unexpected byte order mark (BOM). The header row must exactly match Shopify's expected column names, as any deviation will cause the import to fail or map data to incorrect fields.
Proven strategies to improve your feed performance and product visibility
When updating existing products via CSV, Shopify matches products by their Handle value. Ensure your Handles are consistent between exports and imports to prevent duplicate products from being created. Use a systematic naming convention like brand-product-name-key-attribute for predictable, readable Handles. Avoid changing Handles after products are published, as this changes the product URL and can break existing links and SEO value. If you must change a Handle, set up a URL redirect from the old Handle to the new one to preserve search engine rankings.
Tags in Shopify power automated collections, product filtering, and search refinement. Use a structured tagging system with consistent naming conventions. Include category tags, attribute tags, seasonal tags, and promotional tags. Separate multiple tags with commas in the CSV. Tags are case-insensitive but maintaining consistent casing improves readability. Plan your tag taxonomy before importing to ensure your collections and storefront navigation work correctly from the start. Avoid creating too many tags per product (keep under 250) as this can impact storefront search performance.
Product descriptions in the Body (HTML) field serve dual purposes: convincing customers to buy and helping search engines understand your products. Write unique descriptions for each product (avoid duplicate content from manufacturer descriptions). Structure content with H2/H3 headings, use bullet points for key features, and include relevant keywords naturally. Include sizing information, care instructions, and use-case scenarios. Descriptions between 300 and 1000 words perform best for SEO. Use proper HTML formatting to ensure the content renders correctly on your storefront theme.
The Variant Compare At Price column enables sale pricing across your store. When this field contains a value higher than the Variant Price, Shopify automatically displays the product as on sale with a strikethrough on the original price. This works with most themes out of the box and is recognized by Google Shopping and other sales channels for sale annotations. Use this strategically for promotions, clearance items, or to highlight savings. Ensure the Compare At Price represents a genuine previous selling price to maintain customer trust and comply with advertising regulations.
The Image Alt Text column provides alternative text for product images, which serves both accessibility and SEO purposes. Write descriptive alt text that includes relevant keywords and accurately describes the image content. Good alt text helps visually impaired users understand your products via screen readers and helps search engines index your images for Google Image Search. Each image should have unique, specific alt text rather than generic descriptions. Keep alt text under 125 characters for optimal screen reader compatibility.
Setting accurate variant weights enables Shopify's carrier-calculated shipping to provide real-time shipping rates at checkout. Include both the Variant Weight and Variant Weight Unit columns in your CSV. Consistent weight data across your catalog prevents unexpected shipping cost surprises for customers, reducing cart abandonment. If you use weight-based shipping rates, ensure every product has a weight value. For digital products, set the weight to 0 and mark the Variant Requires Shipping as FALSE.
Shopify supports custom metafields that can store additional product data beyond the standard fields. Metafields are useful for custom specifications, warranty information, care instructions, material composition, or any data that your theme or apps need to display. While the native CSV import has limited metafield support, third-party apps like Matrixify enable metafield columns in CSV imports. Define metafield columns using the format product.metafields.namespace.key for product-level data. This approach keeps your product data centralized and accessible to themes and apps without relying on tags or description parsing.
Shopify acts as the data source for multiple sales channels including Google Shopping, Facebook, Instagram, and TikTok. Ensuring your CSV data is complete and well-structured benefits all connected channels simultaneously. Include fields that channels commonly require: product type for category mapping, vendor for brand identification, tags for collection and filtering, barcode (GTIN/EAN) for product matching, and complete variant attributes. Products missing key fields will fail to sync to specific channels, limiting your multi-channel reach and revenue potential.
Frequent feed issues and how to resolve them
Duplicate Handle creates new product instead of updating existing
When importing a CSV to update existing products, Shopify uses the Handle to match products. If the Handle in your import file does not exactly match the existing product's Handle (including case and special characters), Shopify creates a duplicate product instead of updating the existing one. Export your current products first and use the exact Handles from the export in your import file. When using the overwrite option in Shopify's CSV import, matching Handles will update the existing product. Without the overwrite option, only new Handles are processed.
Variant rows not linked to parent product
Variant rows must have the exact same Handle as the parent product row, and the parent product row must appear first in the CSV. If variant rows have a different Handle or appear before their parent row, they will be created as separate products rather than variants. Ensure the Title column is blank on variant rows (only fill in variant-specific fields like Option Values, SKU, Price, and Inventory). Sort your CSV so that the product row (with Title) always appears before its variant rows (without Title) for each Handle group.
HTML formatting broken in product descriptions
The Body (HTML) column requires proper CSV escaping when the HTML contains commas, newlines, or double quotes. Wrap the entire HTML content in double quotes, and escape any internal double quotes by doubling them ("" instead of "). Avoid line breaks within the CSV cell unless the cell is properly quoted. Validate your HTML before importing to catch unclosed tags or invalid markup. If you are generating the CSV programmatically, use a proper CSV library rather than manual string concatenation to handle escaping automatically.
Image URLs not accessible during import
Shopify downloads product images from the URLs specified in the Image Src column at the time of CSV import. If the images are hosted behind authentication, on a local network, or on a server with geographic restrictions, the import will fail silently for those images. Ensure all image URLs use HTTPS, return a 200 status code, and are publicly accessible without authentication. Test a sample of URLs in an incognito browser window before importing. Images must be in JPEG, PNG, GIF, or WebP format and should be under 20MB per image. Consider hosting images on a CDN for reliable access during large imports.
Inventory quantities not imported correctly for multi-location stores
Inventory import behavior depends on your Variant Inventory Tracker setting and the location configuration in your Shopify store. If you have multiple locations enabled, the Variant Inventory Qty column may not work as expected because Shopify needs to know which location to assign the inventory to. For multi-location stores, use the Shopify inventory CSV format (separate from the product CSV) or manage inventory through the Admin API. Ensure the Variant Inventory Tracker is set to shopify and that your store's location settings match your CSV data. After import, verify inventory levels in the Shopify Admin under Products > Inventory.
Character encoding issues causing garbled text or import failure
Always save your CSV file with UTF-8 encoding. When editing in Excel, use Save As and select CSV UTF-8 (Comma delimited) format. If you see garbled characters (like special characters replaced with question marks or multi-byte sequences), the file was likely saved in a different encoding like Latin-1 or Windows-1252. Avoid opening CSV files directly in Excel as it may auto-detect the wrong encoding. Instead, use the Data > Import From Text/CSV option where you can explicitly select UTF-8 encoding. Google Sheets handles UTF-8 encoding more reliably and is a good alternative for CSV editing.
Key metrics that indicate how well your product feed is performing
The percentage of rows in your CSV that are successfully processed without errors. Aim for a 100% success rate by validating your CSV before import. Shopify sends an email after import completion that details the number of products created, updated, and any rows that failed. Common causes of failure include invalid Handle formats, inaccessible image URLs, missing required fields, and HTML formatting errors. Track this metric across imports to ensure your CSV generation process is producing consistently clean data.
The percentage of products in your catalog that have all key fields populated, including description, images, SEO title, SEO description, variant details, and tags. Products with complete data perform significantly better in site search, collection filtering, and sales channel syndication. Use Shopify's product export to audit completeness and identify products with missing fields. Aim for 95%+ completeness across your catalog, prioritizing your top-selling products.
Track organic search traffic and rankings for product pages to measure the impact of CSV-based content optimization. Well-optimized Body HTML, Image Alt Text, SEO Title (derived from Title), and SEO Description (meta description) directly impact Google rankings. Monitor page-level organic traffic in Google Search Console and compare performance before and after CSV-based content updates. Products with unique, keyword-rich descriptions typically achieve 30% to 50% better organic visibility than those with manufacturer-provided or duplicate content.
The percentage of products that successfully sync to connected sales channels (Google Shopping, Facebook, Instagram, TikTok) without errors. Incomplete product data is the primary cause of sync failures. Products missing required channel-specific attributes (like GTIN for Google Shopping or product category for Facebook) will fail to sync. Monitor sync status in each channel's app within Shopify and trace failures back to missing or incorrect CSV data fields to fix them in your next import.
The percentage of product page visitors who add the product to cart or complete a purchase. Well-structured product data including detailed descriptions, high-quality images, accurate sizing information, and complete variant options directly impacts conversion rates. Shopify's Analytics dashboard shows conversion rates per product. Products with complete data typically convert 2-3x better than products with minimal information. Track conversion rate improvements after CSV-based content updates to measure ROI of data optimization efforts.
Track the correlation between product data completeness and return rates. Products with accurate descriptions, multiple images showing different angles, complete sizing information, and detailed specifications typically have 30-50% lower return rates. Segment your return data by product data quality to identify where improving your CSV data can directly reduce costly returns and improve customer satisfaction.
Step-by-step guide to creating and optimizing your product feed
If you already have products in your Shopify store, start by exporting them as a CSV file. Go to Products > All Products in your Shopify Admin, click Export, and select all products or a specific collection. This export serves as a template with the correct column headers and formatting. If you are starting with an empty store, download the Shopify sample CSV from the documentation to use as a template. Open the file in a spreadsheet application like Google Sheets or Excel to familiarize yourself with the column structure and data requirements for each field.
Map your product data to Shopify's CSV columns. Required fields include Handle (URL-friendly slug), Title, Vendor, Type, Variant SKU, Variant Price, Variant Inventory Qty, Variant Inventory Policy, Variant Fulfillment Service, and Published. For products with variants, enter the main product data on the first row and variant-specific data (Option values, SKU, Price, Inventory) on subsequent rows sharing the same Handle. Fill in optional fields like Body (HTML) for descriptions, Tags for filtering and collections, Image Src for product photos, and Image Alt Text for accessibility and SEO. Ensure all text uses UTF-8 encoding.
Before importing into Shopify, validate your CSV for common issues. Check that all Handles are unique per product and URL-friendly (lowercase, hyphens, no special characters). Verify that all variant rows have the correct parent Handle. Ensure Image Src URLs are publicly accessible by testing a few in your browser. Confirm price values use the correct decimal format without currency symbols. Check that inventory quantities are whole numbers. Validate that Option Names are consistent across products (e.g., always use Size not Sizes). Open the file in a text editor to verify UTF-8 encoding and comma delimiters.
Download our ready-to-use Shopify CSV template with all columns pre-formatted and annotated with examples. This guide covers the complete import workflow, from data preparation to post-import validation, helping you avoid the most common CSV import errors and optimize your product data for maximum Shopify storefront performance.
Common questions about Shopify Product CSV product feeds
WisePIM automatically generates optimized product feeds for all major channels from your central product catalog.