Shopify CSV vs API Import: Which Should You Use for Your Product Catalog?

AEO answer: Shopify offers two product import paths: a native CSV format for one-time or periodic bulk uploads, and the Admin GraphQL API for programmatic, ongoing imports. CSV is simpler but has structural limits: it is a flat format that cannot reliably carry per-variant images or variant-level metafields. The API has no structural limits but requires development effort or a middleware tool. For catalogs under 500 SKUs with simple variant structures, CSV is usually correct. For larger catalogs, ongoing sync, per-variant images, or business-critical metafields, the API is required.

Choosing the wrong Shopify import method does not announce itself immediately. The CSV upload starts, the progress bar moves, and you get an email that says the import completed successfully. Then you open the storefront and the blue hoodie is showing the image for the red one. The metafields are missing. A second batch is needed because the first file hit the 15 MB limit. And now you have 400 products that imported twice under slightly different handles.

The cost of the wrong choice is not the method itself. It is the recovery: manual edits across hundreds of SKUs, a second developer sprint, and a launch that slips by a week.

This guide makes the comparison honest. It covers the verified specs for both import paths as of 2026, the five catalog characteristics that predict which method will work, a feature-by-feature table, real failure modes from practitioner accounts, and a 5-step decision flow that gives you a clear answer for your specific catalog — before you start.

MicroPIM connects to Shopify via the Admin API and handles sync, field mapping, and validation through a configuration interface. See how it works on the supported platforms page.

1. Shopify CSV Import: What It Is and What It Can Actually Do

AEO answer: Shopify’s native product CSV is a flat file format designed for one-time or periodic bulk uploads via the admin interface. It represents products and their variants as a flat row structure — one row per variant, with product-level fields repeated on the first variant row and left blank on subsequent rows for the same product. As of 2026, the file size limit is 15 MB, with a practical row ceiling of 15,000–50,000 rows depending on description and tag length. It does not support per-variant metafields, and per-variant image assignment via CSV is unreliable.

Shopify’s CSV format has been the default entry point for product catalog imports since the platform’s early days. The structure is flat: one row per product variant, with product-level attributes appearing on the first row for each product, and those same columns left blank on every subsequent variant row for that product.

That flat structure is both its strength and its limit.

What CSV handles well

Simple product structures. A product with one or two variants where all variants share the same images imports cleanly. Catalog updates where you are writing over existing data and the product handle already exists in your store are straightforward. One-time migrations from other platforms where the variant count per product is low and the catalog is under a few hundred SKUs stay well within the 15 MB file limit.

What CSV cannot do reliably

Per-variant images. The CSV format has an image column and a variant image column, but both use positional inference — the import engine infers which image belongs to which variant based on row order. Minor manipulation of the file (sorting by price, filtering rows, opening in Excel and saving) silently breaks the positional contract. Wrong images end up on wrong variants with no error in the import report.

Variant-level metafields. Shopify’s CSV supports product-level metafields using a [namespace].[key] column convention — for example, specs.material — but variant metafields are not supported via CSV import at all. Product-level metafield import also has inconsistent behavior for complex types: references, lists, color pickers, and JSON-type metafields do not import reliably and are not clearly flagged in the post-import error report.

Catalogs over the file size limit. At 15 MB, which translates to roughly 15,000–50,000 rows depending on description length, the upload times out. Larger catalogs must be split into multiple files and imported sequentially.

Ongoing sync. CSV is a manual, file-by-file process. Running it weekly or daily is operationally unsustainable and creates handle-collision risk on every re-import.

How CSV import works operationally

You prepare the file according to Shopify’s column spec — UTF-8 encoding with LF linefeeds, BOM characters absent — upload it via Products > Import in the admin, and Shopify processes it asynchronously. Processing completes in minutes for small files and can take hours for files near the size limit. Shopify sends an email when done, with a downloadable error CSV listing which rows failed and why. There is no pre-import validation: errors surface only after the import finishes.

For the full field-by-field walkthrough of the Shopify catalog migration process including CSV column spec, see How to Migrate Your Product Catalog to Shopify.

2. Shopify Admin API: What It Is and What Changed in 2026

AEO answer: Shopify’s Admin API — GraphQL recommended, REST deprecated — allows programmatic product creation and update with no structural file-size limit. The GraphQL Bulk Operations API (bulkOperationRunMutation) accepts a JSONL file up to 100 MB, processes it asynchronously, and reports errors per object. As of 2026-01+, each shop can run up to 5 concurrent bulk mutation operations. Per-variant image assignment uses direct variant ID and image ID references — no positional inference required.

The Admin API gives you access to the full Shopify product data model: every field, every metafield namespace, per-variant image assignment, inventory per location, and publication scope at the collection level. Everything that CSV cannot do.

REST deprecation and GraphQL preference

Shopify has two API variants. The REST Admin API is the older interface — it creates products one at a time. The GraphQL Admin API is the current recommended path. Shopify deprecated REST API endpoints for products as of October 1, 2024, and required all new public apps to use GraphQL as of April 1, 2025. Custom apps that still reference REST product endpoints are receiving “Deprecated endpoint” errors or will soon. New import projects should use GraphQL exclusively.

Bulk Operations API — the right path for catalog-scale imports

For any import beyond a few hundred products, the GraphQL Bulk Operations API is the correct surface. You submit a bulkOperationRunMutation with a JSONL file — one JSON object per line, one product mutation per line — and Shopify processes it asynchronously. Key specs as of 2026:

• JSONL file size limit: 100 MB (versus CSV’s 15 MB)
• Supported record count: 25M+ records per operation
• Concurrent operations: up to 5 per shop on API version 2026-01+ (earlier versions: 1 per shop)
• Processing timeout: 24 hours — operations not complete by then are marked FAILED
• Rate limit status: bulkOperationRunMutation is exempt from standard rate limits; standard GraphQL mutations use a cost-based bucket that refills at a fixed rate

Core mutations and per-variant image assignment

The primary GraphQL mutations for product import are productCreate, productUpdate, productSet, productVariantsBulkCreate, and productVariantsBulkUpdate. Per-variant image assignment uses direct references: you provide the variant ID and the image ID in the same productVariantsBulkUpdate call. There is no positional inference. Reordering your data does not break image assignments.

What API import requires

Using the API directly requires development work: a developer who can write GraphQL mutations, handle OAuth or access token authentication, manage rate limits for standard mutations, and build retry logic for failed objects. Alternatively, a PIM or integration tool can handle the API interaction and expose a configuration interface to non-technical users.

3. The Five Catalog Signatures That Predict Which Method Will Work

AEO answer: Five catalog characteristics predict which Shopify import method will succeed: total SKU and variant row count, per-variant image requirements, metafield dependency, ongoing update frequency, and whether technical resources are available. Each characteristic has a threshold that flips the correct choice from CSV to API. A catalog that trips any one of the API-required thresholds below should use the API — the thresholds are independent.

Rather than starting with “how many SKUs do you have?” and stopping there, evaluate your catalog against five specific signals. Any one of these signals, alone, can make CSV unworkable regardless of the total SKU count.

1. Total variant row count — threshold: 15,000 rows. Your CSV file contains one row per variant, not one row per product. A catalog of 800 products with an average of 20 variants each is 16,000 rows — already past the practical limit of a single 15 MB CSV file. Calculate your variant row count before choosing a method. If it exceeds 15,000, plan for multiple CSV imports or use the Bulk Operations API.

2. Per-variant image requirements — threshold: any color-variant product. If any product in your catalog has different images per variant — color variants are the most common case — CSV’s positional image inference makes wrong-image assignments effectively guaranteed at any meaningful scale. The threshold for flipping to API is one product with variant-differentiated images.

3. Metafield dependency — threshold: business-critical data in metafields. If your catalog carries specifications, compliance data, or custom attributes in metafields that downstream systems depend on, CSV metafield import is not reliable enough. Variant metafields are not supported by CSV import at all. The threshold for flipping to API is one metafield type that CSV cannot import correctly.

4. Update frequency — threshold: more than once per month. CSV is a manual, file-by-file process. If you need to push product updates to Shopify weekly, CSV becomes an operational burden and a handle-collision risk. The threshold for flipping to API is any recurring sync requirement.

5. Technical resources — threshold: none. CSV requires no code. The API requires a developer or a middleware tool. If neither is available and your catalog does not trip thresholds 1–4, CSV may be your only practical path. If any technical resource is available — including a PIM with a native Shopify connector — the API becomes accessible.

4. Feature-by-Feature Comparison Table

AEO answer: The most important differences between Shopify CSV and the Admin GraphQL API are: file size (CSV 15 MB, API 100 MB JSONL), per-variant metafield support (CSV: none; API: full), per-variant image assignment (CSV: positional, fragile; API: direct ID reference), error visibility (CSV: post-import row-level report; API: per-object in output file), and ongoing-sync fitness (CSV: not suitable; API: native).

Sources: Shopify Help Center — CSV, Shopify Dev — Bulk Operations, Shopify Deprecation Timeline

5. When “Both” Is the Right Answer

AEO answer: CSV for first load, API for ongoing sync is the correct pattern when your catalog is large enough that CSV is the faster initial path but ongoing updates need automation. Use CSV to get products into Shopify quickly during migration, then configure an API-based sync — via a PIM or integration tool — for all updates going forward. The handoff risk is handle collision: the second method must treat the existing handles as the authoritative identifiers, not recreate them.

The CSV vs API framing implies you pick one and stay with it. Most mid-market teams end up using both, in sequence.

A catalog of 1,200 products with 6,000 total variant rows is a case where CSV is a viable initial migration path — it is under the file size limit, requires no code, and gets products into Shopify within hours. But the same catalog updated weekly with new arrivals, price changes, and inventory adjustments is not a sustainable CSV workflow. Manual re-exports, handle-collision risk on re-import, and brittle image row ordering make weekly CSV impractical at that scale.

The correct pattern: CSV for the first load, API-based sync for all updates from day one of go-live. Specifically, this applies when your catalog meets all of the following conditions:

• Total variant rows under 15,000 (CSV can handle the initial import in one or two files)
• No per-variant image requirements, or you are prepared to fix those manually post-import
• Simple product-level metafields only, not variant-level
• A PIM or integration tool is available to take over API sync after go-live

The handoff requires care. The API-based sync must use the Shopify product handles and variant IDs that the CSV import created as its reference identifiers — not regenerate them. Any re-import via CSV after the API sync is configured risks overwriting API-managed data with stale CSV values.

For teams evaluating this pattern with a PIM, Bidirectional Product Sync With Shopify covers the sync architecture decisions that determine whether your ongoing data flow behaves predictably.

6. Real Failure Modes From the Field

AEO answer: The five most common Shopify import failures are: CSV row-count explosion when variant multiplication is not accounted for in file planning; image URL timeout when images are on a slow CDN; handle collision when the same catalog is re-imported with overwrite intent but the wrong mode selected; variant image misalignment from sorting a CSV after image URLs were added; and REST-to-GraphQL migration breakage for existing custom apps that still reference deprecated REST endpoints.

These are practitioner-sourced accounts of import failures in mid-market Shopify catalogs. Each one is avoidable with advance planning.

Row-count explosion (1,200 products, 12,000–18,000 variant rows). A team migrating from WooCommerce counted products, not variant rows. Their 1,200-product catalog, with 10–15 variants each, produced 18,000 rows and a 22 MB file. The 15 MB limit forced the file to be split into three batches. The first batch imported successfully. Re-importing the second batch required manually removing the successfully imported rows to avoid handle duplication — an error-prone manual step that added three hours to the migration. Fix: calculate total variant rows before preparing the CSV. If the count exceeds 10,000, use the Bulk Operations API.

Image URL timeout (500 products, 2,000 images). A fashion brand with color-variant products hosted images on a legacy CDN with high latency. Shopify fetches image URLs asynchronously during import; the first 200 products imported with images, then the remaining fetches timed out. The error log showed “Image fetch timeout” with no partial recovery path. Shopify’s guidance is to move images to a faster CDN — Cloudinary or similar — before import, or use the API with retry logic for image assignment after the product records are created.

Handle collision on re-import (300 products). A team exported their catalog, modified pricing in Excel, and re-imported. The re-sort in Excel moved product rows out of order, changing which row had the title. Shopify matched records by handle but some products silently merged or had variants orphaned. Fix: never sort a CSV intended for re-import unless you fully understand the handle-matching behavior. For surgical price updates, use a targeted API call to update only the price field — the Admin API supports field-level updates that do not touch other data.

Variant image misalignment from CSV sorting (100 products, 300 variants). A t-shirt brand with three color variants per product sorted their CSV by price after adding image URLs. The sort broke the positional contract between image rows and variant rows. Post-import, the storefront showed wrong images on the wrong color variants. Per Craftshift’s documented Shopify CSV variant image guide, CSV variant image mapping depends on row order — sorting the file after image URL insertion is the leading cause of this failure mode. Fix: add image URLs as the final step before upload and do not sort afterward. Long term: use the API, which uses direct variant ID plus image ID references and is order-independent.

REST-to-GraphQL migration breakage (5,000 products, 50,000 variants). A custom Shopify app built in 2023 using the REST Admin API for product sync stopped working when its shop’s API version was upgraded. REST API product endpoints were deprecated October 1, 2024, with public apps required to switch to GraphQL by April 1, 2025. The migration required rewriting REST API calls to GraphQL productCreate, productUpdate, and bulkOperationRunMutation calls — a substantial development sprint. Fix: audit any existing Shopify integration for REST API calls to product endpoints and migrate to GraphQL before the deprecation affects your shop’s API version.

For a systematic taxonomy of the most common Shopify migration failures and how to prevent them, see Shopify Migration Failures.

7. The Hidden Third Option: A PIM With a Native Shopify App

AEO answer: A PIM with a native Shopify integration removes the technical barrier to the Admin API. The PIM handles authentication, rate limits, error handling, field mapping, and retry logic. You configure the mapping between PIM attributes and Shopify fields, and the PIM manages the API calls. This makes the API path accessible to non-technical teams, adds pre-sync data validation, and turns a one-time import decision into an ongoing product data operations model.

CSV vs API is a false binary if you have a PIM. The PIM handles the API interaction and exposes it as configuration, not code.

MicroPIM’s native Shopify app

MicroPIM connects to Shopify via a native app that uses the Admin GraphQL API — not REST. The connection uses a custom app with OAuth-scoped access: read_products, write_products, read_inventory, write_inventory, read_locations, read_product_listings, write_metaobjects, and read_metaobjects. The full setup process — creating the custom app in your Shopify Partner dashboard, generating the access token, and configuring the connection in MicroPIM — is covered in Connect MicroPIM to Shopify.

Sync directions and data coverage

Product content flows unidirectionally from MicroPIM to Shopify: titles, descriptions, vendor, product type, tags, handles, variant SKUs, barcodes, prices, compare-at prices, weight, option values, and images. Per-variant images use the direct ID-reference method the Admin API provides — no positional inference, no misalignment risk from file reordering.

Metafields are fully supported. You map PIM attributes to Shopify metafield namespaces and keys in the MicroPIM field mapping interface. Both product-level and variant-level metafields are covered — the capability gap that CSV cannot bridge.

Inventory data flows selectively in the other direction: Shopify order fulfillment writes inventory level changes back to MicroPIM. Shopify product and variant IDs write back as reference identifiers so MicroPIM can issue targeted update calls rather than full re-creates. This selective bidirectionality — product content flows PIM-to-Shopify, inventory writes back from Shopify to PIM — is the correct architecture for most mid-market teams. The reasoning behind that model is explained in detail in Bidirectional Product Sync With Shopify.

Drift detection logs any Shopify-side edits to product content made directly in the Shopify admin, before those edits are overwritten by the next sync cycle. This prevents silent data loss when a team member makes a quick edit in Shopify that has not been propagated back to the master record in MicroPIM.

Sync cadence options

Sync runs via three mechanisms: real-time via Shopify webhooks for inventory changes, scheduled cron at configurable intervals (every 15 minutes, hourly, or daily) for product content, and on-demand via a “Sync Now” trigger for immediate pushes after catalog enrichment work.

Per-product health score gates sync

Before a product is pushed to Shopify, MicroPIM computes a per-product health score across content quality dimensions — completeness (required and optional fields populated), accuracy (values within expected ranges), consistency (standard formatting applied), and richness (optional enhancement fields). Products below a configured quality threshold are blocked from syncing to Shopify until the specific gaps are resolved. The score-gated sync enforces a quality standard at the workflow level: incomplete or inaccurate products do not make it to the storefront automatically. The full health score methodology — including how SEO and GEO readiness dimensions integrate with content quality — is covered in the product health score guide.

Weekly product health score reports

Store owners and catalog managers connected to a Shopify store in MicroPIM can receive weekly health score email digests scoped to the Shopify-connected catalog. The digest covers score-band distribution across the connected product set (what percentage of your Shopify catalog is in each quality tier this week versus last week), category-level average scores, week-over-week deltas, the products with the sharpest score declines, the products that improved most, and a prioritized action list for the coming week. The report is designed for operations leads who are not in the PIM every day but need to know whether catalog quality is drifting before it shows up as a performance problem on the storefront.

On-demand catalog SEO reports

For the Shopify-connected catalog, MicroPIM surfaces on-demand SEO reports that evaluate product titles, meta descriptions, image alt text, and Product schema completeness against the content standards that affect Shopify storefront SEO. Three AI-assisted tools connect directly to SEO report findings: the SEO Name Optimizer rewrites supplier codes and generic names into search-optimized product titles; the Meta Tags Optimizer generates spec-compliant meta titles and descriptions for products missing them; and the Attributes Builder identifies schema-relevant attribute gaps and suggests values from the product’s existing data. The SEO report is scoped to the Shopify-facing content — it reflects what is being pushed to the storefront, not a crawl of the rendered Shopify pages.

Explore the full feature set that MicroPIM brings to a Shopify-connected catalog — see the features overview.

8. Decision Flow: Which Method Should You Pick Today?

AEO answer (HowTo): To choose between Shopify CSV and API import: (1) Count your total variant rows — if over 15,000, go to Step 5 (API required). (2) Check per-variant image needs — if any product needs different images per variant, go to Step 5 (API required). (3) Check metafield requirements — if business-critical metafields are needed, especially at the variant level, go to Step 5 (API required). (4) Check update frequency — if updates are needed more than once per month, go to Step 5 (API required). (5) Assess technical resources — no resources and none of steps 1–4 triggered: use CSV. Technical resources available (developer or PIM): use the API.

Use this flow before committing to either method. Each step is a binary check.

Step 1 — Count your total variant rows. Multiply your product count by your average variant count per product. If the result exceeds 15,000, skip to Step 5: CSV cannot handle this catalog in a single file and the multi-file workaround adds risk. API required.

Step 2 — Audit per-variant image needs. Does any product in your catalog require different images for different variants? Color variants are the most common case. If yes, skip to Step 5. CSV’s positional image inference is not reliable enough for production use with variant-differentiated images. API required.

Step 3 — Audit metafield requirements. Does your catalog carry data in metafields that is business-critical — specifications, compliance data, custom attributes downstream systems rely on? Do any of those metafields live at the variant level? If yes, skip to Step 5. Variant metafields are not supported via CSV, and product-level metafield import for complex types is unreliable. API required.

Step 4 — Determine update frequency. Will this import be a one-time event, or do you need to push updates more than once a month? If updates are ongoing, skip to Step 5. CSV is a manual, per-file process — it is not a viable ongoing sync mechanism. API required.

Step 5 — Assess technical resources. If none of Steps 1–4 sent you here: you have a small, simple, one-time catalog. CSV is your correct path — use it. If any of Steps 1–4 sent you here: you need the API. Do you have a developer available or a PIM with a native Shopify connector? If yes, use the API (directly or via PIM). If no, evaluate a PIM with a native Shopify app before concluding that CSV is your only option — it likely is not.

Frequently Asked Questions

What are Shopify’s CSV import limits?

Shopify’s CSV import has a 15 MB file size limit. In practice, this translates to 15,000–50,000 rows depending on description and tag length per row. Stores with more than 50,000 existing variants are also subject to a quota of 1,000 new variants per 24 hours, which applies to CSV uploads. Large catalogs must be split into multiple files and imported sequentially, which introduces handle-collision risk if not managed carefully. For catalogs that would require more than two or three CSV files, the Bulk Operations API is a more reliable path.

How many products can you import into Shopify at once?

Via CSV: as many products as fit in a single 15 MB file — roughly 15,000–50,000 rows depending on row length. Via the Bulk Operations API: up to 25M+ records per JSONL file, with a 100 MB file size limit and a 24-hour processing timeout. As of API version 2026-01+, you can run up to 5 concurrent bulk operations per shop, which means very large catalogs can be parallelized across multiple JSONL files submitted simultaneously.

When should I use Shopify API vs CSV?

Use CSV for catalogs under 500 SKUs with simple variant structures, no per-variant image requirements, no business-critical metafields, and a one-time migration context. Use the API for any catalog that has per-variant images, variant-level metafields, more than 15,000 total variant rows, an ongoing sync requirement, or a team with a developer or PIM tool available. The API produces consistently better results at any scale but requires more setup. For catalogs in the middle range — 500 to 5,000 SKUs — the decision turns on variant image and metafield requirements, not just size.

What is the Shopify Bulk Operations API?

The Bulk Operations API is a GraphQL feature that accepts a JSONL file — one JSON object per line, one product mutation per line — and processes it asynchronously. It is submitted via the bulkOperationRunMutation GraphQL mutation. Shopify processes the operation against the full file, commits successful objects immediately, and produces a per-object error report for failed objects. Key specs: 100 MB JSONL file size limit, 25M+ supported records, 24-hour processing timeout, 5 concurrent operations per shop on API version 2026-01+. bulkOperationRunMutation is exempt from standard GraphQL rate limits.

Is Shopify’s REST API being deprecated?

Yes. Shopify deprecated REST API product endpoints on October 1, 2024, and required all new public apps to use the GraphQL Admin API as of April 1, 2025. Existing custom apps referencing deprecated REST endpoints will receive errors on affected API versions. Shopify’s guidance is to migrate to the GraphQL Admin API — specifically to productCreate, productUpdate, productSet, and bulkOperationRunMutation for product imports. New integrations built in 2025 or later should not use REST for product operations.

Do I need a developer to use the Shopify Admin API?

For a direct integration, yes — the API requires code for authentication, GraphQL query and mutation construction, rate limit management, and error handling. However, a PIM with a native Shopify connector abstracts that work into configuration. You define field mappings, set a sync schedule, and trigger syncs from a UI — the PIM handles the API calls, rate limiting, and error recovery. For teams without development resources, a PIM with a native Shopify app is the realistic path to using the Admin API without writing code. For a broader look at what a PIM does and when your catalog operation needs one, see PIM for E-Commerce: What It Does, When You Need One.

MicroPIM connects to Shopify via the Admin GraphQL API and handles field mapping, validation, health score gating, and ongoing sync through a configuration interface — no custom code required. Book a demo and we will walk through your catalog’s specific import requirements together.