Metafield definitions

One row creates one metafield definition — the field itself, not its value. name, key, type and ownerType are required; everything else is optional.

Template available

Choose Metafield definitions on the upload step and click Download template. It comes with a correct header row and several example rows, each demonstrating a different case, and it imports as-is.

A worked example

metafield-definitions.csv

name,key,type,ownerType,namespace,description,pin,validations,storefrontAccess
Care guide,care_guide,multi_line_text_field,PRODUCT,custom,How to care for this product,true,,PUBLIC_READ
Reading time,reading_time,number_integer,ARTICLE,custom,Minutes to read,true,min:1;max:120,PUBLIC_READ
Highlights,highlights,list.single_line_text_field,PRODUCT,custom,Key selling points,false,,PUBLIC_READ
Written by,written_by,metaobject_reference<author>,ARTICLE,custom,Who wrote this,false,,PUBLIC_READ

Four definitions, four credits. The last row uses the metaobject reference shorthand — see reference types.

Columns

Required

Column	What it controls	Example
`name` Required	Human-readable name shown in the Shopify admin.	`Care guide`
`key` Required	2–64 characters, letters, numbers, hyphens and underscores only. Unique within its namespace. This is the part you'll use in themes and APIs.	`care_guide`
`type` Required	The metafield data type. Reference types accept the `metaobject_reference<author>` shorthand. A type can never be changed after creation.	`multi_line_text_field`
`ownerType` Required	The resource the definition attaches to. See owner types.	`PRODUCT`

Optional

Column	What it controls	Example
`namespace`	Groups related metafields. Defaults to `custom` when left blank. 3–255 characters, same character set as the key.	`custom`
`description`	Internal note explaining what the metafield stores. Shown to staff in the admin.	`How to care for this product`
`pin`	`true` pins the definition to the top of the admin editor, so staff see it without hunting.	`true`
`validations`	Constraints on accepted values. See validations.	`min:1;max:120`
`adminAccess`	`MERCHANT_READ` or `MERCHANT_READ_WRITE`.	`MERCHANT_READ_WRITE`
`storefrontAccess`	`NONE` or `PUBLIC_READ`. Use `PUBLIC_READ` to expose the field to your theme.	`PUBLIC_READ`
`customerAccountAccess`	`NONE`, `READ` or `READ_WRITE`.	`NONE`
`adminFilterable`	`true` to allow filtering admin lists by this metafield.	`false`
`uniqueValues`	`true` to reject duplicate values across resources.	`false`
`smartCollectionCondition`	`true` to allow this metafield to be used as a condition in automated collections.	`false`
`analyticsAggregate`	`true` to allow filtering or grouping data by this metafield in Analytics.	`false`

Not every flag applies to every type

Shopify restricts some capabilities to particular metafield types — you can't make a rich text field filterable in the admin, for example. ImportKit passes your value through and lets Shopify be the authority, so an unsupported combination comes back as a row error naming the problem rather than being silently dropped.

Metafield types

ImportKit recognises 113 metafield types, including every list.* variant Shopify supports. The common ones:

For	Use
A short string	`single_line_text_field`
A paragraph or more	`multi_line_text_field`
Formatted text with headings and links	`rich_text_field`
Whole numbers	`number_integer`
Decimals	`number_decimal`
A yes/no toggle	`boolean`
A date, or a date and time	`date`, `date_time`
A price	`money`
A measurement	`weight`, `dimension`, `volume`
A star rating	`rating`
A link	`url`
A colour swatch	`color`
Arbitrary structured data	`json`
A link to another object	`product_reference`, `collection_reference`, `file_reference`, `page_reference`, `variant_reference`, `metaobject_reference`
Several of any of the above	Prefix with `list.`, e.g. `list.single_line_text_field`

Shopify caps how many you can have

256 definitions per owner type, and 50 pinned per owner type. These are the two limits ImportKit doesn't yet count for you, so a large generated file can pass the pre-import check and then fail on the rows that cross the line. Shopify's limits →

A misspelled type is a warning, not an error

Type multi_line_text_fied and the pre-import check flags it with a suggested spelling but still lets the row through. That's deliberate: Shopify adds types faster than any app can track, so Shopify stays the authority on what it will accept. If it really is a typo, Shopify rejects the row and the credit is refunded.

Reference types and the metaobject shorthand

A metaobject_reference field can be pointed at one specific metaobject definition, so the admin only offers entries of that type. ImportKit accepts the same shorthand Shopify's own configuration files use:

shorthand.csv

name,key,type,ownerType
Written by,written_by,metaobject_reference<author>,ARTICLE
Related recipes,recipes,list.metaobject_reference<recipe>,PRODUCT

ImportKit looks up the author definition, finds its ID, and stores it as a validation on the new field. If that definition doesn't exist yet, the row still imports — but with a warning explaining that the field will accept any metaobject rather than only authors. Import your metaobject definitions first to avoid that.

Validations

Two accepted formats, whichever is easier in your spreadsheet:

Format	Example cell
`name:value` pairs separated by `;`	`min:1;max:120`
A JSON object	`{"min":"1","max":"120"}` — remember to quote the cell

Which validation names are available depends on the type: min and max for numbers and dates, max for text length, choices for a fixed list, regex for a pattern, and so on. Shopify's metafield type documentation is the authority; ImportKit passes them through and reports whatever Shopify says.

Owner types

Given the permissions ImportKit requests, you can define metafields on these 13 owner types:

ARTICLE, BLOG, CARTTRANSFORM, COLLECTION, DELIVERY_CUSTOMIZATION, DISCOUNT, LOCATION, MARKET, PAGE, PAYMENT_CUSTOMIZATION, PRODUCT, PRODUCTVARIANT, VALIDATION

Customer, order, draft order, company and gift card owner types are not available, because ImportKit doesn't request those permissions. A row targeting one is reported individually with the exact missing permission, and the rest of your file still imports. Why, and the full list →

The mapping step narrows this for you

ImportKit shows the owner types your store's granted permissions actually cover, as a banner above the mapping table. So you'll see the constraint before you've finished building the file, not after.

Note the spelling: it's PRODUCTVARIANT, with no underscore. Get it wrong and you'll see ownerType "PRODUCTS_VARIANT" is not valid — did you mean "PRODUCTVARIANT"? with the row number.

Rules enforced before anything reaches Shopify

Key — 2–64 characters, letters, numbers, hyphens, underscores.
Namespace — 3–255 characters, same character set, defaults to custom.
Reserved namespaces are rejected — $app, app--…, shopify--… and shopify belong to Shopify and apps. A CSV import creates merchant-owned definitions, so these can't be used.
Duplicates within the file — two rows with the same ownerType + namespace + key: the second is flagged duplicate of row N.
Type changes — if a definition already exists with a different type, the row is a conflict in every conflict mode. Shopify makes types immutable, and quietly doing something else would be worse than saying so.

Re-importing the same definitions

A definition is identified by ownerType + namespace + key, so re-running a file always collides. Your conflict mode decides what happens:

Mode	Result	Charged
Skip (default)	The existing definition is left completely alone.	No
Update	Name, description, pin, access and validations are overwritten with the row's values. The type is never changed.	Yes
Fail	Reported as a row-level error.	No

Now put values in them

Import metafield values onto real products, referencing them by handle or SKU.

The pre-import check

Catch invalid keys, bad owner types and reserved namespaces before spending anything.