ImportKit
Metaobject entries
One row creates one entry of a metaobject definition you already have. This is the bulk-loading import — 200 store locations, 50 authors, every ingredient in your catalogue.
This is the only import type without fixed columns. Pick a target definition on the upload step and ImportKit generates the column list from that definition's own fields — which is also why there's no downloadable template. The upload step's column reference shows you exactly what's available for the target you chose.
Choose the target first
On the upload step, after selecting Metaobject entries, pick the definition from the target dropdown. It's listed by name and type, like Author (author).
Changing the target changes the available columns, so choose it before you build the file — or use the column reference to see what a definition needs.
No definitions in the list? Import one first.
Target selector with the column reference open
Content type set to Metaobject entries, target set to Author (author), and the “Show column reference” table expanded to reveal handle, status, name, bio and photo.
assets/screenshots/metaobject-entries-target.png
Columns
Always present
| Column | What it controls | Example |
|---|---|---|
handle Required |
The entry's unique identifier within this type. Re-importing the same handle updates or skips that entry rather than creating a duplicate. Letters, numbers, hyphens and underscores. | jane-doe |
status |
ACTIVE or DRAFT. Only appears if the definition is
publishable.
|
ACTIVE |
One column per definition field
Everything else comes from your definition. For an author definition
with name, bio and photo, you get three more
columns, each with help text and an example value appropriate to its type.
Fields the definition marks required are required here too. Optional fields can be left out of the file entirely, or left blank per row.
A worked example
For the author definition from the previous page:
handle,status,name,bio
jane-doe,ACTIVE,Jane Doe,Writes about product design.
john-roe,DRAFT,John Roe,Covers manufacturing and logistics.
alex-kim,ACTIVE,Alex Kim,"Photographer, and occasional copywriter."
Three entries, three credits. The third row is quoted because the bio contains a
comma. The photo column is left out entirely, which is fine — it's
optional.
Handles
The handle is the entry's identity, so it deserves a moment's thought:
- It must be unique within the definition type. Duplicates in the same file are flagged as
duplicate of row N. - Letters, numbers, hyphens and underscores only. No spaces, no slashes, no accents.
-
Make it derivable from your source data —
jane-doefrom “Jane Doe”,store-berlin-mittefrom a location name. That way a second import from an updated export lines up with the entries you already created, instead of making new ones.
=LOWER(SUBSTITUTE(TRIM(A2)," ","-")) turns a name column into
serviceable handles. Check the results for stray punctuation before importing.
Field values
Each column is converted based on that field's type in the definition. The formats are the same everywhere in ImportKit — the value format reference has the full list. The ones that come up most in metaobject entries:
| Field type | Cell contents |
|---|---|
single_line_text_field | Jane Doe |
multi_line_text_field | Plain text; quote the cell to include line breaks. |
rich_text_field | Plain text, HTML, or Shopify rich text JSON — all converted for you. |
boolean | true / false |
number_integer, number_decimal | 10, 10.5 |
date | 2026-01-31 |
url | https://example.com |
money | {"amount":"5.99","currency_code":"USD"} |
file_reference | gid://shopify/MediaImage/123 |
product_reference | gid://shopify/Product/123 |
metaobject_reference | Another entry's handle, e.g. jane-doe, or a full gid://shopify/Metaobject/123 |
Any list.* | Comma-separated, newline-separated, or a JSON array. |
Blank cells are skipped rather than written, so an empty cell can't clear a value on an existing entry.
More on reference fields, including the 250-entry lookup limit →
Re-importing entries
Entries are identified by handle within the type, so an updated export
lines up with what you already imported. The conflict mode decides what happens:
| Mode | Result | Charged |
|---|---|---|
| Skip (default) | The existing entry is left alone. | No |
| Update | The mapped fields are overwritten on the existing entry. Fields not in your file are untouched. | Yes |
| Fail | Reported as a conflict. | No |
Update mode makes this import type a decent ongoing sync: re-export from your source, keep the handles stable, and run it again. Only the columns you map get overwritten.
Patterns that work well
A definition and its entries in one sitting
- Import the definition. One row, one credit.
- Check it in Settings → Custom data → Metaobjects.
- Start a new import, choose Metaobject entries, and pick it as the target.
- Open the column reference to see the exact column names, and build your file to match.
Entries that reference each other
If entries of one type point at entries of another — recipes referencing ingredients, say — import the referenced type first. References resolve by handle, so the target has to exist when the referring row is processed.
Draft first, publish later
For a publishable definition, import everything with status set to
DRAFT, review the entries in the admin, then flip them to
ACTIVE — either in the admin, or by re-importing the same file with
ACTIVE in Update mode.
One limit worth knowing
When a reference is resolved by handle, ImportKit looks through the first
250 entries of the referenced type. Beyond that, use a full
gid://shopify/Metaobject/… value, which needs no lookup at all. Entry
collision detection — the part that decides create versus update — is fully
paginated and isn't affected.