Skip to main content

Product Fields

Import and export product data including details, variants, images, inventory, pricing, and additional attributes.

Updated this week

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:

  1. 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.

  2. 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.

  3. 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:

  1. By Variant ID: Searches Shopify to find the product containing this specific variant

  2. By SKU: Searches across all product variants to find products containing variants with matching SKUs

  3. 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:

  1. By Variant ID: Direct match using the variant's unique identifier

  2. 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

  3. 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

8901234567890

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

premium-cotton-tee

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

  • 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

Premium Cotton T-Shirt

The main product title displayed to customers throughout your store.

Body HTML

Description

Example Value

Product description

<p>Soft, breathable cotton for comfort</p>

Full product description supporting HTML formatting for rich content display.

Vendor

Description

Example Value

Product manufacturer/brand

Comfort Wear

The company or brand that manufactures or supplies the product.

Type

Description

Example Value

Product category

Apparel

Free-form text field for categorizing products within your store.

Tags

Description

Example Value

Comma-separated product tags

cotton, casual, bestseller

Tags help organize products and enable customer filtering and search functionality.

Tags Command

Description

Example Value

Tag operation: ADD, REPLACE, REMOVE, MERGE

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

2024-03-15 09:30:00 -0500

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

2024-06-20 14:45:00 -0500

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

  • 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

  • TRUE: Product is published and visible to customers

  • FALSE: Product is unpublished and hidden from customers

Published At

Description

Example Value

Publication timestamp

2024-03-16 10:00:00 -0500

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

web

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

featured-item

Allows using alternative Liquid templates for displaying this specific product.

Gift Card

Description

Example Value

Gift card designation: TRUE, FALSE

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

https://store.myshopify.com/products/premium-cotton-tee

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

247

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

3

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

TRUE

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

sg-4-17-2-17

The unique identifier for the product's assigned category from Shopify's product taxonomy.

Category: Name

Description

Example Value

Category name

T-Shirts

The display name of the product's category.

Category

Description

Example Value

Full category path

Apparel > Men > T-Shirts

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

summer-favorites, staff-picks

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

cotton-products, under-50

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

IMAGE

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

https://cdn.example.com/tshirt.jpg or photo.jpg

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

  • 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

1

Determines the order in which media files appear on the product page.

Image Width

Description

Example Value

Media width in pixels - Export only

1200

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

1200

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

Front view of cotton t-shirt

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

45678901234

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

12345678901

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

  • 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

Size

The name of the first product option (e.g., Size, Color, Material).

Option1 Value

Description

Example Value

First option choice

Large

The specific value for the first option that defines this variant.

Option2 Name

Description

Example Value

Second option category

Color

The name of the second product option.

Option2 Value

Description

Example Value

Second option choice

Navy Blue

The specific value for the second option that defines this variant.

Option3 Name

Description

Example Value

Third option category

Material

The name of the third product option.

Option3 Value

Description

Example Value

Third option choice

Cotton

The specific value for the third option that defines this variant.

Variant Position

Description

Example Value

Display order of variant

2

Determines the order in which variants appear when customers view options.

Variant SKU

Description

Example Value

Stock keeping unit

TCT-LG-NVY

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

123456789012

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

https://cdn.example.com/navy.jpg

URL of the image that represents this specific variant.

Variant Weight

Description

Example Value

Product weight value

0.5

Numeric weight value for shipping calculations.

Variant Weight Unit

Description

Example Value

Weight unit: kg, g, lb, oz

kg

  • 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

29.99

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

39.99

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

  • 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

clothing

Code used for tax calculation purposes in different jurisdictions.

Variant Inventory Tracker

Description

Example Value

Inventory tracking: shopify, blank

shopify

  • 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

deny

  • continue: Allow purchases when out of stock

  • deny: Prevent purchases when inventory reaches zero

Variant Fulfillment Service

Description

Example Value

Fulfillment service identifier

manual

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

  • TRUE: Variant requires physical shipping

  • FALSE: Digital product that doesn't require shipping

Variant Inventory Qty

Description

Example Value

Current stock level

150

The available quantity for this variant in your default location.

Variant Inventory Adjust

Description

Example Value

Quantity adjustment

25

Relative change to current inventory (use - for decrease).

Variant Cost

Variant Cost

Description

Example Value

Cost per unit

12.50

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

6109.10.00

International trade classification code for customs and tariff purposes.

Variant Country of Origin

Description

Example Value

Manufacturing country code

CN

Two-letter ISO country code indicating where the product was manufactured.

Variant Province of Origin

Description

Example Value

Manufacturing province/state

Guangdong

Province or state where the product was manufactured within the country of origin.

Variant Unit Price

Description

Example Value

Unit pricing details

{"quantityUnit": "G", "quantityValue": 12.0, "referenceUnit": "KG", "referenceValue": 1}

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

1023

The available inventory quantity at the location.

Inventory Available Adjust

Description

Example Value

Adjustment to quantity

-5

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

  • 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

34.99

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

44.99

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 handle

  • title: Filter by product title

  • barcode: Filter by product barcode

  • category_id: Filter by category ID

  • collection_id: Filter by collection ID

  • inventory_total: Filter by total inventory quantity

  • price: Filter by product price

  • product_type: Filter by product type

  • sku: Filter by SKU

  • variant_id: Filter by variant ID

  • variant_title: Filter by variant title

  • vendor: Filter by vendor name

  • created_at: Filter by creation date

  • updated_at: Filter by last update date

  • published_at: Filter by publish date

  • gift_card: Filter by whether the product is a gift card

  • is_price_reduced: Filter by whether the product has a reduced price

  • tag: Filter by tag (include)

  • tag_not: Filter by tag (exclude)

  • publishable_status: Filter by publication status (published, unpublished)

Did this answer your question?