When importing data with multiple rows per product (such as products with multiple variants or images), rows are grouped together to form complete product objects. The grouping and search hierarchy works as follows:
Product and Variant Grouping
Product-Level Grouping
When your spreadsheet contains product-level fields (ID, Handle, or Title), the system groups rows using this priority order:
By ID: If a product ID is present, all rows with the same ID are grouped together. The system searches Shopify to find existing products by their unique identifier.
By Handle: If no ID is provided or no matching product is found, rows with matching handles are grouped together. The system searches for products using the handle.
By Title: If neither ID nor handle is provided, rows with identical titles are grouped together. The system searches for products with exact title matches. Note: If multiple products have the same title, the import will fail with an error.
Variant-Level Grouping
When your spreadsheet only contains variant-level identifiers (no product ID, handle, or title columns), the system uses variant fields to locate the parent product:
By Variant ID: Searches Shopify to find the product containing this specific variant
By SKU: Searches across all product variants to find products containing variants with matching SKUs
By Barcode: Searches by barcode across product variants (only when no SKU or Variant ID columns exist)
Variant Matching Within Products
When updating existing products, variants within the product are matched using this priority:
By Variant ID: Direct match using the variant's unique identifier
By Option Combination: Creates a hash from the variant's option values (Option1 Value, Option2 Value, Option3 Value) to match variants with identical option combinations
By SKU: Normalizes and compares SKU values to find matching variants
Multiple media files, inventory levels, and other sub-data are also grouped under their parent product using this same hierarchy.
Sample File
Download a sample spreadsheet to see the structure for importing product data.
General
ID
Description | Example Value |
Shopify's unique product identifier |
|
The ID and Handle fields work together to group multiple rows into a single product object (for example, when importing multiple variants). If an ID is present, the app will first try to find an existing product using the ID. If no ID match is found, the app will attempt to locate the product using the Handle.
Handle
Description | Example Value |
URL-friendly product identifier |
|
The handle creates the product's URL path and must be unique within your store. When no ID is provided or no product is found by ID, the Handle serves as the fallback identifier for locating existing products during import.
If you do not provide a handle Shopify will generate one for you based on the product title.
Command
Description | Example Value |
Import action: MERGE, DELETE, NEW, REPLACE, IGNORE |
|
MERGE: Update existing product or create if not found
DELETE: Remove the product from your store
NEW: Create product only (fails if product exists)
REPLACE: Delete existing product and create new one
IGNORE: Skip this product row during import
Title
Description | Example Value |
Product name |
|
The main product title displayed to customers throughout your store.
Body HTML
Description | Example Value |
Product description |
|
Full product description supporting HTML formatting for rich content display.
Vendor
Description | Example Value |
Product manufacturer/brand |
|
The company or brand that manufactures or supplies the product.
Type
Description | Example Value |
Product category |
|
Free-form text field for categorizing products within your store.
Tags
Description | Example Value |
Comma-separated product tags |
|
Tags help organize products and enable customer filtering and search functionality.
Tags Command
Description | Example Value |
Tag operation: ADD, REPLACE, REMOVE, MERGE |
|
ADD: Append new tags to existing tags
MERGE: Same as ADD - append new tags to existing tags
REPLACE: Replace all existing tags with specified tags
REMOVE: Remove specified tags from the product
Created At
Description | Example Value |
Product creation timestamp - Export only |
|
The date and time when the product was originally created in Shopify. This field is export-only and cannot be imported.
Updated At
Description | Example Value |
Last modification timestamp - Export only |
|
The most recent date and time the product was modified. This field changes any time a product or variant field is updated, including when inventory is adjusted. This field is export-only and cannot be imported.
Status
Description | Example Value |
Product status: ACTIVE, DRAFT, ARCHIVED |
|
ACTIVE: Product is published and available for purchase
DRAFT: Product is saved but not published to customers
ARCHIVED: Product is hidden from all sales channels
Published
Description | Example Value |
Publication status: TRUE, FALSE |
|
TRUE: Product is published and visible to customers
FALSE: Product is unpublished and hidden from customers
Published At
Description | Example Value |
Publication timestamp |
|
When the product was or will be published. Future dates schedule publication.
ISO-formatted timestamps (e.g., 2024-03-16T10:00:00Z
) are also supported. When no timezone is specified, your store's timezone is used.
Published Scope
Description | Example Value |
Publication visibility scope |
|
Legacy field that determines where the product appears within your store's sales channels. Options are:
web: Product is visible on the web
global: Product is visible on all sales channels
Template Suffix
Description | Example Value |
Custom template identifier |
|
Allows using alternative Liquid templates for displaying this specific product.
Gift Card
Description | Example Value |
Gift card designation: TRUE, FALSE |
|
TRUE: Product functions as a digital gift card
FALSE: Regular physical or digital product
URL
Description | Example Value |
Full product page URL - Export only |
|
The complete URL to the product page. This field is export-only and cannot be imported.
Total Inventory Qty
Description | Example Value |
Combined inventory across all variants - Export only |
|
Sum of inventory quantities for all product variants. This field is export-only and cannot be imported.
Row
Description | Example Value |
Row identifier for multi-row data |
|
Used when product data spans multiple spreadsheet rows (e.g., multiple variants or media files).
Top Row
Description | Example Value |
Primary product row indicator: TRUE, FALSE |
|
This field is used to identify the main product row in a multi-row import. If you have multiple variants, images, or other sub-data, you can quickly see unique products by filtering for TRUE
in this column.
TRUE: Main row containing primary product information
FALSE: Additional row for variants, media, or other sub-data
Category
Product categories use Shopify's standardized product taxonomy to classify items consistently across your store and sales channels.
Category: ID
Description | Example Value |
Category identifier |
|
The unique identifier for the product's assigned category from Shopify's product taxonomy.
Category: Name
Description | Example Value |
Category name |
|
The display name of the product's category.
Category
Description | Example Value |
Full category path |
|
Complete hierarchical path showing the product's categorization.
Collections
Collections group products together to help customers browse and find related items. Manual collections require you to add products individually, while smart collections automatically include products based on rules you define.
Custom Collections
Description | Example Value |
Manual collections containing products |
|
Comma-separated list of manual collections where this product appears. Collections are identified by their handle.
Smart Collections
Description | Example Value |
Automated collections - Export only |
|
Comma-separated list of smart collections that automatically include this product based on rules. Collections are identified by their handle.
Images / Media
Image Type
Description | Example Value |
Media file type |
|
Specifies the type of media file being uploaded or referenced.
IMAGE: Standard image files (JPEG, PNG, GIF, etc.)
VIDEO: Video files uploaded to Shopify
MODEL_3D: 3D model files for augmented reality
FILE: General file attachments
EXTERNAL_VIDEO: Videos hosted on Vimeo or YouTube
Image Src
Description | Example Value |
Media file URL or filename |
|
URL to media file or filename of existing file already uploaded to your store.
You can provide multiple URLs separated by semicolons or commas to upload multiple files at once. Alternatively, use multiple Image Src columns for different media files.
Image Command
Description | Example Value |
Media operation |
|
MERGE: Update existing media or add if not found
DELETE: Remove specified media from product
REPLACE: Remove all existing media and add new media
IGNORE: Skip this media row during import
Image Position
Description | Example Value |
Display order number |
|
Determines the order in which media files appear on the product page.
Image Width
Description | Example Value |
Media width in pixels - Export only |
|
The width dimension of the media file. This field is export-only and cannot be imported.
Image Height
Description | Example Value |
Media height in pixels - Export only |
|
The height dimension of the media file. This field is export-only and cannot be imported.
Image Alt Text
Description | Example Value |
Alternative text for accessibility and SEO |
|
Descriptive text for screen readers and SEO purposes when images cannot be displayed.
Inventory / Variants
Variant Inventory Item ID
Description | Example Value |
Inventory item identifier - Export only |
|
Internal Shopify identifier for the variant's inventory item. This field is export-only and cannot be imported.
Variant ID
Description | Example Value |
Unique variant identifier |
|
Shopify's unique identifier for the specific product variant. When no product-level identifiers (ID, Handle, Title) are provided, the system can use Variant ID to locate the parent product. When updating existing products, Variant ID takes priority over other variant matching methods.
Variant Command
Description | Example Value |
Variant operation |
|
MERGE: Update existing variant or create if not found
DELETE: Remove the variant from the product
NEW: Create variant only (fails if variant exists)
REPLACE: Delete existing variant and create new one
IGNORE: Skip this variant row during import
Option1 Name
Description | Example Value |
First option category |
|
The name of the first product option (e.g., Size, Color, Material).
Option1 Value
Description | Example Value |
First option choice |
|
The specific value for the first option that defines this variant.
Option2 Name
Description | Example Value |
Second option category |
|
The name of the second product option.
Option2 Value
Description | Example Value |
Second option choice |
|
The specific value for the second option that defines this variant.
Option3 Name
Description | Example Value |
Third option category |
|
The name of the third product option.
Option3 Value
Description | Example Value |
Third option choice |
|
The specific value for the third option that defines this variant.
Variant Position
Description | Example Value |
Display order of variant |
|
Determines the order in which variants appear when customers view options.
Variant SKU
Description | Example Value |
Stock keeping unit |
|
Unique identifier for inventory tracking and management purposes. When no product-level identifiers are provided, SKU can be used to locate the parent product. When updating existing products, SKU is used as a fallback method for matching variants when Variant ID is not available.
Variant Barcode
Description | Example Value |
Product barcode |
|
UPC, EAN, or other barcode identifier for the variant. When no product-level identifiers, Variant ID, or SKU columns are provided, Barcode can be used as a final fallback to locate the parent product.
Variant Image
Description | Example Value |
Variant-specific image URL |
|
URL of the image that represents this specific variant.
Variant Weight
Description | Example Value |
Product weight value |
|
Numeric weight value for shipping calculations.
Variant Weight Unit
Description | Example Value |
Weight unit: kg, g, lb, oz |
|
kg: Metric weight measurement (kilograms)
g: Metric weight measurement (grams)
lb: Imperial weight measurement (pounds)
oz: Imperial weight measurement (ounces)
Variant Price
Description | Example Value |
Regular selling price |
|
The standard price customers pay for this variant. Use decimal format only (no commas or currency symbols), with period as the decimal separator.
Variant Compare At Price
Description | Example Value |
Original or reference price |
|
The original or MSRP price shown crossed out to indicate savings. Use decimal format only (no commas or currency symbols), with period as the decimal separator.
Variant Taxable
Description | Example Value |
Subject to taxes: TRUE, FALSE |
|
TRUE: Variant is subject to applicable taxes
FALSE: Variant is exempt from taxes
Note: Gift card products are automatically set to non-taxable regardless of this field value.
Variant Tax Code
Description | Example Value |
Tax classification |
|
Code used for tax calculation purposes in different jurisdictions.
Variant Inventory Tracker
Description | Example Value |
Inventory tracking: shopify, blank |
|
shopify: Shopify tracks inventory quantities for this variant
Blank field: Inventory tracking is disabled for this variant
When creating new variants without inventory quantity data, tracking is automatically disabled.
Variant Inventory Policy
Description | Example Value |
Out-of-stock behavior: continue, deny |
|
continue: Allow purchases when out of stock
deny: Prevent purchases when inventory reaches zero
Variant Fulfillment Service
Description | Example Value |
Fulfillment service identifier |
|
Specifies which service handles fulfillment for this variant. During export, this is automatically set to manual
for regular products and gift_card
for gift card products.
Variant Requires Shipping
Description | Example Value |
Shipping requirement: TRUE, FALSE |
|
TRUE: Variant requires physical shipping
FALSE: Digital product that doesn't require shipping
Variant Inventory Qty
Description | Example Value |
Current stock level |
|
The available quantity for this variant in your default location.
Variant Inventory Adjust
Description | Example Value |
Quantity adjustment |
|
Relative change to current inventory (use - for decrease).
Variant Cost
Variant Cost
Description | Example Value |
Cost per unit |
|
The cost you pay for each unit of this variant, used for profit calculations. Use decimal format only (no commas or currency symbols), with period as the decimal separator.
Customs Information
Variant HS Code
Description | Example Value |
Harmonized System trade code |
|
International trade classification code for customs and tariff purposes.
Variant Country of Origin
Description | Example Value |
Manufacturing country code |
|
Two-letter ISO country code indicating where the product was manufactured.
Variant Province of Origin
Description | Example Value |
Manufacturing province/state |
|
Province or state where the product was manufactured within the country of origin.
Variant Unit Price
Description | Example Value |
Unit pricing details |
|
JSON object containing unit pricing measurement information for regulatory compliance.
The Variant Unit Price field requires a JSON object with this structure:
{ "quantityUnit": "G", "quantityValue": 12.0, "referenceUnit": "KG", "referenceValue": 1 }
Valid Units: CL, CM, FLOZ, FT, FT2, G, GAL, IN, ITEM, KG, L, LB, M, M2, M3, MG, ML, MM, OZ, PT, QT, YD
Field Requirements:
quantityUnit
: Unit for the quantity (from valid units list)quantityValue
: Numeric quantity value (decimal allowed)referenceUnit
: Reference unit (from valid units list)referenceValue
: Reference value (whole number required)
Multi-Location Inventory Levels
For each location, use column names like Inventory Available: My Custom Location
and Inventory Available Adjust: My Custom Location
where "My Custom Location" is replaced with your actual location name.
Inventory Available
Description | Example Value |
Available quantity in the location |
|
The available inventory quantity at the location.
Inventory Available Adjust
Description | Example Value |
Adjustment to quantity |
|
Specifying relative inventory change at the location (use - to indicate direction).
Pricing by Markets
Use column names with market names in the format Included / Belgium
, Price / Belgium
, Compare At Price / Belgium
where "Belgium" is replaced with your specific market name.
Included
Description | Example Value |
Market availability: TRUE, FALSE |
|
TRUE: Variant is available in the specified market
FALSE: Variant is excluded from the specified market
Use market names in column headers like Included / US
or Included / Canada
.
Price
Description | Example Value |
Market-specific price |
|
Price for the variant in the specified market's currency.
Use market names in column headers like Price / US
or Price / Canada
.
Compare At Price
Description | Example Value |
Market-specific reference price |
|
Original or MSRP price for the variant in the specified market's currency.
Use market names in column headers like Compare At Price / US
or Compare At Price / Canada
.
When setting a compare-at price for a market, you must also provide the regular price for that same market. Markets without catalogs will have them created automatically during import.
Metafields and SEO
Metafields can be imported and exported with products to store custom data, SEO information, and additional attributes. This includes the title_tag
and description_tag
fields for SEO meta titles and descriptions.
For rich text metafields (type rich_text_field
), you can provide HTML content that will automatically convert to Shopify's JSON format during import.
For detailed information about working with metafields, see our Metafields guide.
Export Filters
You can use these filters to limit which products are exported:
handle
: Filter by product handletitle
: Filter by product titlebarcode
: Filter by product barcodecategory_id
: Filter by category IDcollection_id
: Filter by collection IDinventory_total
: Filter by total inventory quantityprice
: Filter by product priceproduct_type
: Filter by product typesku
: Filter by SKUvariant_id
: Filter by variant IDvariant_title
: Filter by variant titlevendor
: Filter by vendor namecreated_at
: Filter by creation dateupdated_at
: Filter by last update datepublished_at
: Filter by publish dategift_card
: Filter by whether the product is a gift cardis_price_reduced
: Filter by whether the product has a reduced pricetag
: Filter by tag (include)tag_not
: Filter by tag (exclude)publishable_status
: Filter by publication status (published, unpublished)