Shopify Bulk Product Upload: CSV Columns, Variant Images and Errors to Avoid | Stuv AI Blog
Chat with us
Shopify Bulk Product Upload: CSV Columns, Variant Images and Errors to Avoid
Home/Blog/Shopify Bulk Product Upload: CSV Columns, Variant Images and Errors to Avoid
Shopify & Platforms

Shopify Bulk Product Upload: CSV Columns, Variant Images and Errors to Avoid

A detailed guide to bulk uploading products and images to Shopify: required CSV columns, how Image Src and Variant Image work, the 15 MB limit, common import errors, and when to use an API-based tool.

S
Stuv AI Team
··13 min read

Shopify gives merchants three built-in ways to change many products: the product CSV import, the bulk editor in the admin, and apps that use the Admin API. Each is right for different jobs. This guide focuses on the CSV — the most powerful option and the easiest to get wrong — and then covers when an API-based tool is the better choice.

Choosing the right method

JobBest methodWhy
Change prices, inventory, tags on selected productsAdmin bulk editorSpreadsheet-like editing in the admin; no file handling
Create a new collection of products with variantsCSV importOne file creates products, options, variants and images
Rewrite descriptions for hundreds of productsCSV import or API toolBody (HTML) is editable in CSV; an API tool avoids re-exporting
Add new images to existing products and map them to variantsAPI toolCSV image handling is URL-based and easy to break
Ongoing sync from another catalog systemAPI toolCSV is a one-off; syncing needs repeatable automation

How the Shopify product CSV is structured

Always start by exporting a few existing products and using that file as your template — Shopify’s columns change over time, and the export always reflects the current format.

ColumnWhat it doesWatch out for
HandleThe product’s unique identifier and URL slug. Rows with the same handle belong to the same product.A typo creates a new, duplicate product.
TitleProduct nameOnly on the first row of each product.
Body (HTML)Description, as HTMLUnescaped quotes or line breaks can break the row in some spreadsheet apps.
Vendor, Type, TagsOrganisation and filteringTags are comma-separated inside the cell.
Published / StatusVisibilityImport as draft first when testing.
Option1 Name / Option1 Value (to Option3)Variant options such as Colour, SizeOption names only on the first row; values on every variant row.
Variant SKU, Variant Price, Variant Compare-at PricePer-variant dataPrices without currency symbols.
Variant Inventory Qty / Tracker / PolicyStockInventory import behaviour depends on location setup.
Image SrcAdds an image to the product galleryMust be a public http(s) URL Shopify can download.
Image Position, Image Alt TextGallery order and accessibility/SEO textPosition 1 is the featured image.
Variant ImageThe image shown when that variant is selectedThe URL must also appear in the product’s Image Src list.

Worked example: a sofa in three colours

Each variant is a row; extra gallery images are extra rows with only the handle and image columns filled.

HandleTitleOption1 NameOption1 ValueVariant SKUVariant PriceImage SrcImage PositionVariant Image
aria-3-seater-sofaAria 3-Seater SofaColourBeigeARIA-3S-BG42999https://…/aria-beige-front.jpg1https://…/aria-beige-front.jpg
aria-3-seater-sofaGreyARIA-3S-GR42999https://…/aria-grey-front.jpg2https://…/aria-grey-front.jpg
aria-3-seater-sofaTealARIA-3S-TL44999https://…/aria-teal-front.jpg3https://…/aria-teal-front.jpg
aria-3-seater-sofahttps://…/aria-beige-room.jpg4

Limits and rules to know

  • File size: a product CSV can’t exceed 15 MB. Split larger catalogs into several files.
  • Encoding: save as UTF-8, or rupee symbols, accented names and Hindi text can corrupt.
  • Overwrite option: when importing, Shopify can overwrite products with matching handles. Blank cells in an overwrite import can clear existing values — export first, edit that file, and keep a backup.
  • Images by URL only: CSV import can’t upload image files directly. Host them somewhere public (or upload to Content → Files and copy the URLs) first.

Common import errors and fixes

SymptomLikely causeFix
Duplicate products after importHandles changed or contain spaces/uppercase inconsistenciesMatch handles exactly to the export
Images missingImage URLs not public, redirected, or blockedOpen each URL in a private browser window; use direct links
Variant shows wrong photoVariant Image URL not in the product’s Image Src rowsAdd the URL to Image Src as well
Descriptions cut off or rows shiftedLine breaks or quotes broke the CSV structureEdit in Google Sheets and export as CSV; avoid Excel auto-formatting
Upload times outFile too large or too many images to fetchSplit into smaller files

Variant images that help customers choose

  • Drive images from the option shoppers compare visually — usually colour or finish, not size
  • Use the same angle as the first image for every colour so switching feels consistent
  • Write alt text with product, colour and view: “Aria 3-seater sofa in teal, front view”
  • Add at least one in-context image per product; room or lifestyle images help shoppers judge scale

A safe bulk-update routine

  1. Export all products as a backup and store it with the date.
  2. Export the products you intend to change and edit that file.
  3. Import 5–10 products first, as drafts if they are new.
  4. Check them on the storefront on mobile: gallery order, variant switching, description formatting.
  5. Import the rest in files well under 15 MB.
  6. Spot-check a random sample after import.

When to use an API-based tool instead

CSV works for one-off imports. It becomes painful when content changes continuously — new AI-generated images every week, refreshed descriptions, seasonal image swaps — because every change means exporting, editing and re-importing. Tools built on the Shopify Admin API can push images and descriptions directly to products and variants and sync new products back.

Stuv’s Shopify Bulk Ops works this way: it connects through Shopify OAuth, pushes images, videos and descriptions from your Stuv catalog to matching products and variants, imports products and manages collections in bulk.

Sources

Frequently Asked Questions

What is the file size limit for Shopify product CSV imports?

A product CSV can’t exceed 15 MB. Split larger catalogs into multiple files.

How do I add images to Shopify variants with a CSV?

Put the image URL in the Variant Image column on the variant’s row, and make sure the same URL also appears in the product’s Image Src rows. URLs must be publicly accessible.

Why did my Shopify CSV import create duplicate products?

Usually because handles didn’t match existing products exactly. Export existing products and edit that file so handles stay identical.

Related Articles

Stuv AI tools for this

See it in action — start free

Turn one product photo into studio images, lifestyle scenes, editorial creatives, and product videos in under 60 seconds.

#Shopify-CSV-import#Shopify-bulk-upload-images#Shopify-variant-images#Shopify-bulk-product-editor