A supplier sends a new product file on Friday afternoon. It looks straightforward: update prices, add new colours, and leave everything else alone. Then the import finishes and a few carefully edited descriptions are blank. Some variants appear twice. Nobody is sure which rows need another attempt.
The hard part of a Shopify product import is deciding exactly what each row is allowed to change. Before choosing an app or writing an API integration, define how products are matched, which system owns each field, and what happens when only part of the job succeeds.
Choose CSV or a custom integration based on the job
A one-off catalogue update with a reviewed file may be a good fit for Shopify’s built-in CSV importer. A recurring supplier feed usually needs more control: saved mappings, validation, an approval step, and a record of previous runs. Product count alone should not decide the approach. A small file with inconsistent identifiers can cause more trouble than a large, clean one.
Shopify’s product CSV import guidance explains that the overwrite option matches existing products by handle. With overwriting enabled, a blank non-required column can replace the existing value with a blank; omitting that column generally preserves its value. Fields with dependencies need extra care.
For example, if you only intend to change prices, do not include an empty Vendor column as harmless padding. Start from the current Shopify format, review the dependent columns, and test a small representative sample.
Give every product and variant a dependable identity
Product names make poor matching keys. “Cotton Shirt” might describe several products, and a merchant can rename a product without intending to create a new one. Decide on a stable supplier identifier, then save its mapping to the Shopify product and variant IDs after a confirmed write.
If you use SKUs for matching, first check your actual catalogue for blanks and duplicates. Do not assume they uniquely identify a variant. An ambiguous match should stop that row for review rather than let the importer guess.
- Store the supplier name and supplier item ID alongside the Shopify IDs.
- Reject conflicting identifiers before sending any changes.
- Keep product-level fields separate from variant-level fields such as size, colour, SKU and price.
- Treat a missing item in a supplier file as a review case unless you have explicitly agreed on a deletion policy.
AI-generated photorealistic editorial image of folded garments, blank tags, a barcode scanner and an inventory sheet. Conceptual retail stock-checking scene, not documentary evidence or a project screenshot.
Conceptual editorial image generated with AI; not a photograph of a client project.
Agree on who owns each field
A supplier may own cost and availability while the store owner writes the title, description and search metadata. If the importer replaces every field simply because it exists in the feed, the next run can undo that work.
Write down a short field policy. For a clothing store, it might say: update supplier cost after validation; flag unusually large price changes for approval; keep merchant descriptions; create new products as drafts pending review; never delete an existing variant because one feed omitted it. These are business decisions to settle before implementation.
A preview should show changes in plain language: “42 prices will change, 6 products will be created, 3 rows need review.” Let the reviewer inspect old and proposed values. A percentage threshold can help catch a misplaced decimal, but the store owner should choose that threshold.
Be careful with productSet and partial variant lists
For custom integrations, Shopify provides the productSet mutation for synchronising product data. Its list fields have replacement-style behaviour: entries omitted from a supplied list can be deleted. Other field types update when included and remain unchanged when omitted.
Imagine a shirt with six variants. The supplier sends a price correction for only the medium blue variant. Sending that single variant as though it were the complete variants list can remove the others. Decide whether you have a complete product snapshot or a partial change before selecting the mutation.
For a narrow variant update, review the dedicated variant mutations linked in Shopify’s documentation. Test the exact input against your chosen API version. A successful response should also be checked for userErrors and the expected resulting data.
Use bulk operations when the workload calls for them
Shopify’s bulk import guide describes an asynchronous workflow: prepare a JSONL variables file, obtain an upload target with stagedUploadsCreate, upload it, start bulkOperationRunMutation, and retrieve the results after completion. Each JSONL line supplies one mutation’s variables.
The guide also warns that lines are not processed in a guaranteed sequence. Do not put “create this product” on one line and assume a later line can immediately use its new ID. Split dependent work into separate stages and save confirmed IDs between them.
Bulk processing changes how the work runs; your importer still needs its own validation and recovery rules. Pin an API version, check its current limits, and avoid starting overlapping jobs that change the same products. For ordinary requests, follow Shopify’s API limit guidance and use controlled retries rather than immediately resending every failed request.
Make partial failure visible and recoverable
For a hypothetical 500-row import, suppose 480 changes succeed, 15 rows fail validation, and 5 have an uncertain outcome after a connection problem. “Import failed” is too vague to act on. Retrying all 500 as new creations risks duplicates.
Keep a run ID and a row-level record containing the source identifier, intended change, Shopify IDs, outcome and error details. Save confirmed successes. Fix validation failures before retrying them. For uncertain outcomes, query the current Shopify state and reconcile the mapping before deciding whether to resend.
An import should finish with a report the merchant can use: created, updated, unchanged, rejected and awaiting reconciliation. Keep that report separate from raw server logs, and avoid storing access tokens or unnecessary personal data in either.
Test the mistakes you actually expect
- Run the same approved file twice and confirm it does not create duplicate products.
- Include duplicate and missing identifiers and confirm they are held for review.
- Test blank optional CSV cells and a file that omits those columns.
- Send a partial variant change and confirm unrelated variants survive.
- Interrupt a run, resume it, and confirm previously successful rows are handled safely.
- Check a sample in Shopify Admin and on the storefront, including images, options, prices and publication status.
Keep a pre-import export for comparison, but do not treat it as a universal undo button. A recovery plan should identify which fields can be restored, how newly created records are handled, and who approves destructive corrections.
Build the import around the store’s workflow
A well-organised catalogue supports the storefront experience. My Zarmina Khan Shopify project shows how collection presentation and theme development bring a clothing catalogue together.
If you need a supplier feed, a recurring catalogue sync or a custom Shopify import tool, I can help define the field rules and build a reviewable process. A useful starting point is one sample file and a clear list of what the importer may change.
Official documentation checked on 30 October 2026. Confirm mutation behaviour and limits against the API version your integration uses.
