Reference
Metaobject CSV format: link products, collections and images without GIDs
Shopify stores references as GIDs — long internal IDs that are impractical to work with in a spreadsheet. Metaobjectify lets you use values you already know instead: product handles, collection handles and direct file URLs.
Quick reference
Four kinds of value cover almost every metaobject CSV.
Product reference
Use the product handle
classic-oxford-shirt
Collection reference
Use the collection handle
mens-shirts
Image or file
Use a direct URL
https://example.com/images/slim-fit-chart.jpg
Entry handle
Lowercase letters, numbers and hyphens
slim-fit-shirt-guide
Worked example: a size guide
Say your store has a Size guide metaobject with these fields. Each one becomes a column in the CSV.
| Field | Type | CSV column |
|---|---|---|
| Entry handle | Handle | handle |
| Title | Single line text | title |
| Fit description | Single line text | fit_description |
| Product | Product reference | product |
| Collection | Collection reference | collection |
| Size chart image | File (image) | size_chart_image |
One row of that CSV
handle,title,fit_description,product,collection,size_chart_image
slim-fit-shirt-guide,Slim Fit Shirt Size Guide,Cut close to the body,classic-oxford-shirt,mens-shirts,https://example.com/images/slim-fit-chart.jpg
| handle | title | fit_description | product | collection | size_chart_image |
|---|---|---|---|---|---|
| slim-fit-shirt-guide | Slim Fit Shirt Size Guide | Cut close to the body | classic-oxford-shirt | mens-shirts | https://example.com/images/slim-fit-chart.jpg |
The product, collection and image are plain handles and a URL — no GIDs anywhere in the file.
Value formats
What to enter for each type of field.
| Field type | What to enter | Example |
|---|---|---|
| Entry handle | Lowercase letters, numbers and hyphens | slim-fit-shirt-guide |
| Text | Plain text | Slim Fit Shirt Size Guide |
| Product reference | The product’s handle | classic-oxford-shirt |
| Collection reference | The collection’s handle | mens-shirts |
| Image or file | A direct URL to the file | https://example.com/images/slim-fit-chart.jpg |
How rows are matched
The handle decides what happens to each row, so one file can update and create entries at the same time.
Existing handle
Updates that entry in place
New handle
Creates a new entry
- Column order and header names don’t matter — you match each column to a field when you import.
- Every row is validated and errors are flagged before anything changes in your store.
Common mistakes — and what to enter instead
Validation flags each of these before import, but it’s quicker to get them right in the spreadsheet.
A product title instead of its handle
Wrong:Classic Oxford ShirtRight:classic-oxford-shirt
A full product link instead of the handle
Wrong:https://yourstore.com/products/classic-oxford-shirtRight:classic-oxford-shirt
A preview or share page instead of a direct file URL
Wrong:https://example.com/share/slim-fit-chartRight:https://example.com/images/slim-fit-chart.jpg
An entry handle changed by accidentThis creates a new entry instead of updating the old one.
Wrong:slim-fit-shirt-guide-2Right:slim-fit-shirt-guide
A file in the wrong format for the field
Wrong:…/slim-fit-chart.pdfRight:…/slim-fit-chart.jpg
Try it on your own metaobjects
The Free plan includes 5 imports and unlimited exports.