Export & Import

Download entries as CSV, import entries from spreadsheets, and share definitions between Shopify stores.

Quick Overview

Feature	What It Does	Limits
CSV export	Downloads your metaobject entries as a spreadsheet	Up to 5,000 entries per definition
CSV import	Creates or updates entries from a spreadsheet	250 rows max, 5MB max
Definition export	Saves definition structure as a JSON file	Structure only — no entry data
Definition import	Creates a new definition from a JSON file	Structure only — no entry data

CSV Export

CSV export lets you download your metaobject entries as a spreadsheet file you can open in Excel, Google Sheets, or any other spreadsheet tool. Use it to back up data, analyze entries, or share information with colleagues.

How to export

1. Open a definition in the bulk editor.
2. Optionally, use search, filters, or sorting to narrow what gets exported.
3. Click the Export CSV button in the toolbar.
4. Your browser downloads the file automatically.

What gets exported

• All displayed entries — respects your active search, filters, and sorting
• All fields in the definition — even if some columns are hidden in the table
• Display Name and Handle columns for easy identification
• Status column when the definition supports publishing

The file opens correctly in Excel and Google Sheets without extra import steps.

How different field types appear in CSV

Field Type	CSV Format	Example
Text fields	Plain text	Summer Collection
Numbers	Plain number	42
Boolean (Yes/No)	Yes or No	Yes
Dates	Standard date format	2026-03-12
References	Handle-first format for portability	summer-tee | gid://shopify/Product/123
Lists	Pipe-separated values	Red | Blue | Green
Rich text	Rich text JSON (preserves formatting on re-import)	Use Flatten rich text option for plain text instead
JSON	Compact JSON	{"key":"value"}

CSV Import

Import entries from a CSV file to create new entries or update existing ones in bulk.

File limits

• Maximum file size: 5MB
• Maximum rows: 250
• File type: .csv

Create vs. update

The Handle column controls what happens with each row:

• Handle has a value — Structa updates the matching entry, or creates a new one if no entry with that handle exists
• Handle is empty or missing — Structa creates a new entry

How columns are matched

Structa automatically maps your CSV column headers to definition fields. It tries exact field keys first, then exact field names, then case-insensitive names. You can also adjust the mapping manually in the preview step.

• Display Name is informational only — it is not sent to Shopify
• For publishable definitions, you can set Status per row or force one value for all rows
• Duplicate handles in your CSV are flagged in the preview

Supported value formats

Structa automatically converts common spreadsheet values:

• Booleans: Yes/No, true/false, 1/0
• Numbers, dates, and colors
• Structured fields like money, rating, weight, volume, and dimension (as JSON)
• List fields: pipe-separated (Red | Blue | Green) or JSON arrays

Empty cells clear the field value where Shopify allows it.

Reference fields

Structa can automatically match references for the most common types:

• Products — by handle, title, or SKU
• Collections — by handle or title
• Metaobjects — by handle or display name
• Files — by filename

For other reference types (customers, variants, pages, articles, etc.), use Shopify GIDs in your CSV. If a required reference can't be matched, that row will fail. If an optional reference can't be matched, Structa skips the value and continues.

How to import

1. Open the import flow in Structa and upload your CSV file.
2. Review the column mapping, duplicate handle warnings, and row summary.
3. Run the import — you'll see created, updated, and failed counts as it progresses.

Definition Export

Export the structure of a metaobject definition as a JSON file. This saves the blueprint — fields, types, validations, and settings — not the actual entry data.

Definition exports are useful for:

• Backups — Save a copy of how your definition is set up
• Sharing — Send the JSON file to a colleague who can import it into another store
• Version control — Track how your definition changes over time

In the bulk editor, click Export Definition — the JSON file downloads automatically.

Definition Import

Import a metaobject definition from a JSON file to create a new definition in your store.

1. On the definitions page, click Import Definition.
2. Upload a Structa definition export or a compatible JSON file.
3. Review the name, type, description, and field list.
4. If the type already exists, choose a different name or use the suggested alternative.
5. Click Import definition to create it.

Troubleshooting

CSV import was rejected

Check that the file is a .csv, smaller than 5MB, and no more than 250 rows.

Some imported rows failed

This happens when individual rows have validation errors or reference values that can't be matched. Review the row-level errors, fix those rows in your CSV, and import again.

Reference columns didn't import

For product, collection, metaobject, and file references, make sure your values match existing handles, titles, or filenames. For other reference types, use Shopify GIDs.

CSV opened with garbled characters

This shouldn't happen — Structa's CSV files are formatted for Excel and Google Sheets. If you're having issues, try opening the file directly rather than pasting the contents.

Imported a definition but the entries didn't come with it

That's expected — definition import only copies the structure. To move entry data, export entries as CSV from the source store and import the CSV after creating the definition in the destination store.

Can I edit fields after importing a definition?

Yes. After importing, you can edit field names, descriptions, and validations, add or remove fields, or change field types from the definition management page.

Best Practices

• Filter before exporting — If you have many entries, use search and filters to export manageable batches
• Keep handles clean — A consistent Handle column makes updates reliable
• Use GIDs for uncommon reference types — Handles and titles work for products, collections, metaobjects, and files; use GIDs for everything else
• Back up definitions regularly — Export your definitions as JSON before making large schema changes
• Test imports first — Try with a small sample CSV before importing hundreds of rows