Shopify's own limits

Shopify caps how many definitions you can have, how big a metafield value can be, and how many items fit in a list. Those limits apply to everyone using the Admin API, so they apply to your imports too. This page lists the ones that affect ImportKit, and is honest about which we catch for you.

This page is about Shopify's limits, not ours

ImportKit's own file size, row count, throughput and pagination limits are on ImportKit's limits. The two are unrelated: you can be well inside our 50 GB file limit and still have a row Shopify refuses.

What ImportKit checks, and what it doesn't

Worth reading before the tables, because it changes how you use them.

Checked before anything is written

All of this is validated as you upload and reported per row by the free pre-import check, so you fix it without spending a credit:

Metafield value size, per type — 64 KB for most, 128 KB for json, 2 KB for url and id. Measured in bytes, so accented and non-Latin text counts correctly.
List item counts — 128 for most list types, 1,024 for metaobject references — plus the size of each individual item.
The number of fields in a metaobject definition, against Shopify's 40.
The number of values in a choices validation, against 128.
Metafield key 2–64 and namespace 3–255 characters, their character sets, and reserved prefixes.
Metaobject definition type 3–255 and field key 2–64 characters, and duplicate field keys.
Metaobject entry handle character set and length.
Article handle length and URL-safety, tag count and length.
published_at being a date Shopify can parse, and image_url being a valid http or https URL.
Owner type, access and status values against Shopify's enums, and JSON validity of the validations and fields cells.

Errors block, inferences only warn

Where Shopify publishes a limit, breaking it is a row error — the row can't import, and the check says so. Where we've inferred a limit that Shopify doesn't publish (article handle length, tag counts, metaobject handle length), a violation is a warning instead: the row still imports. Being wrong about an unpublished number must never block a valid import.

Still discovered at write time

A few limits depend on your whole store rather than one row, and ImportKit doesn't yet count them:

The 256 definitions per owner type ceiling, and how many your file would add.
The number of pinned definitions, against 50.
The admin-filterable and smart-collection-condition ceilings.
The length of any name or description, which Shopify doesn't publish a limit for.
Whether an image_url is actually reachable — the format is checked, but we don't fetch it.

When Shopify refuses a row for one of these, ImportKit passes its message through verbatim into that row's result, refunds the credit, and carries on with the rest of the file. So it costs nothing — but it's a second pass, which is why the list above is short and getting shorter.

ImportKit never truncates

Some importers silently shorten an over-long value to fit. ImportKit doesn't — a value is either written as you wrote it or reported as a problem. Quietly storing 255 of your 300 characters is a worse outcome than telling you, because you'd never know to look.

ImportKit never truncates

Some importers silently shorten an over-long value to fit. ImportKit doesn't — a value is either written as you wrote it or reported as a failed row. Quietly storing 255 of your 300 characters is a worse outcome than telling you, because you'd never know to look.

Metafield definition counts

Limit	What it means for an import
256 definitions per resource type, for the merchant	Per owner type, not overall — so 256 on products, another 256 on articles, and so on. Each installed app gets its own separate allowance of 256 per resource type. Definitions ImportKit creates are merchant-owned, so they count against your allowance, not an app's.
50 pinned definitions per resource type	The `pin` column is where this bites. Setting `pin` to `true` on more than 50 definitions for one owner type will start failing rows once the limit is reached. Pin the ones staff actually use.
Standard definitions are generally excluded	Shopify's own standard definitions don't normally count against these limits.

A definitions import of a few dozen rows is nowhere near this. A generated file creating hundreds of product fields could hit it, and ImportKit won't warn you in advance — it doesn't count your existing definitions against a ceiling.

Metafield value sizes

This is the limit most likely to affect a real metafield values import, because long descriptions and HTML add up fast.

Type	Maximum value size
Most metafield types	64 KB (65,536 bytes)
`json`	128 KB
`url`	2 KB
`id`	2 KB

Note these are bytes, not characters. Accented characters, emoji and most non-Latin scripts take more than one byte each, so a 64 KB ceiling is fewer than 65,536 characters for a lot of real content.

Two related notes from Shopify

Values over 10,000 bytes aren't returned to Shopify Functions. The value is still stored and the Admin API still returns it, but a function sees nothing — relevant if you're feeding discount or checkout logic.
Apps that were using JSON fields before April 2026 are grandfathered at a higher 2 MB ceiling, and larger JSON limits can be requested. That grandfathering applies to apps, not to merchant-owned definitions created from a CSV.

List lengths

Limit	What it means for an import
128 items in any `list.*` metafield	A comma-separated cell with more than 128 entries will be rejected. This is easy to hit accidentally when a cell was built by concatenating a column.
1,024 items for `list.metaobject_reference`	The one generous exception, for linking many entries.
Each item carries its type's own size limit	An item in a `list.single_line_text_field` gets the same 64 KB ceiling as a standalone one — the list limit is on count, not on total size.
128 predefined choices for single-line text	If you're supplying a `choices` validation, that's the ceiling. Validations →
`list.min` / `list.max` validations	You can set your own tighter bounds through the `validations` column, within Shopify's maximums.

Remember ImportKit's own list rule while you're here: a cell containing line breaks uses newlines as the separator instead of commas, which is how you store items that themselves contain commas. Value formats →

Definition capability limits

These constrain the optional flag columns on a metafield definitions import.

Capability	Limit per resource type
`smartCollectionCondition` — usable in automated collections	128
`adminFilterable` — on products, companies, company locations or metaobjects	50
`adminFilterable` — on orders	5
`pin`	50

Shopify also restricts some capabilities to particular metafield types. ImportKit passes your flag through and lets Shopify be the authority, so an unsupported combination comes back as a row error naming the problem.

Metaobject limits

Limit	What it means for an import
40 fields per metaobject definition	A direct cap on your `fields` cell — no more than 40 `key:type` pairs in one row. ImportKit checks that you have at least one field, but doesn't count the upper bound. The fields column →
128 definitions per shop on Basic, Shopify and Advanced; 256 on Plus and Enterprise	Merchant-owned definitions, which is what a CSV import creates. Each installed app gets a separate allowance of 128.
1,000,000 entries per definition	Effectively unlimited for a CSV import — you'd hit ImportKit's own 1,000,000 row per import ceiling at the same moment.
50 filterable metaobject field definitions	The admin index can filter on up to 50 fields.

Metaobject entry lookups

Separate from Shopify's limits, ImportKit resolves a metaobject reference by handle or name across only the first 250 entries of a type. Past that, use a full gid://shopify/Metaobject/… value. Why →

Blog article limits

Shopify doesn't publish a limits page for articles the way it does for metafields and metaobjects, so this section is deliberately shorter and hedged rather than confidently wrong.

Field	What to expect
`handle`	Shopify handles are generally capped at 255 characters and must be URL-safe. ImportKit does not validate or slugify your handle — it's passed through as written, so a handle with spaces or punctuation is Shopify's to accept or reject. Leave the column out and Shopify generates one from the title.
`tags`	Shopify documents a limit of 250 tags per product, and individual tags are generally capped at 255 characters. Article tags aren't documented separately. ImportKit splits your cell on commas and trims each tag, but doesn't count or length-check them.
`title`	Not length-checked by ImportKit. Only its presence is required.
`body_html`, `summary_html`	Sent as Shopify's HTML type, so Shopify validates the markup. No size check on our side.
`published_at`	Must be a date Shopify can parse — ISO 8601, such as `2026-03-18T09:00:00Z`. ImportKit does not validate the format, so a malformed date fails the row at write time.
`image_url`	Must be publicly reachable when the import runs, because Shopify fetches it. ImportKit does not check that it's a valid or reachable URL.

Articles get no pre-import check either

Blog articles are the one type with no check step, so none of the above is visible before the run. Import a five-row sample first — especially on a blog migration, where dates and image URLs are the usual culprits.

Sanity-check your file against these

Quick things to run in your spreadsheet before a large import:

No value cell longer than roughly 60,000 characters — =MAX(LEN(E2:E999)) will tell you.
No list cell with more than 128 items — count the commas.
No fields cell with more than 40 key:type pairs.
Fewer than 50 rows with pin set to true per owner type.
Your existing definition count for that owner type, plus this file's rows, is under 256.
Every published_at value parses as a date.
Every image_url is publicly reachable right now.
Article handles contain no spaces or punctuation.

Rate limits

Shopify also throttles how fast an app can call the Admin API. ImportKit handles this for you rather than exposing it: rows are sent strictly one at a time, and a row rejected for throttling is retried up to three times with a short back-off. It's the main reason a large import takes minutes rather than seconds. Throughput →

These numbers move

Shopify raises and adjusts limits regularly — the metaobject entry ceiling was raised substantially in late 2025, for instance. The figures here were checked against Shopify's documentation at the time of writing, but Shopify's own pages are the authority. That's also why ImportKit treats an unrecognised metafield type as a warning rather than an error: our list of what Shopify accepts will always lag Shopify's.

Found a limit that affects an import and isn't listed here? Tell us at support@importkit.app and we'll add it.

Sources

Shopify's documentation for the figures above:

Metafield limits — definition counts, value sizes, list lengths, capability limits
Metaobject limits — definition counts by plan, fields per definition, entries per definition
List of validation options — what the validations column can contain
List of data types — every metafield type and its own constraints
articleCreate — the article fields ImportKit writes

Limits summarised and paraphrased from Shopify's documentation; follow the links for the authoritative wording.

ImportKit's limits

File size, row counts, throughput, retries and pagination — our constraints rather than Shopify's.

Error messages

What a Shopify rejection looks like in your job results, and how to narrow one down.