Export & Import

Download entries as CSV and share definitions as JSON between stores.

CSV Export of Entries

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

In the bulk editor, click the Export CSV button in the top toolbar, next to the definition name. The button shows how many entries are ready to export.

What gets exported

• All currently displayed entries — respects your active filters, search, and column visibility settings
• All fields — every field in your definition becomes a column in the spreadsheet
• Display name and handle — the first two columns for easy identification

How different field types are formatted

Different field types display differently in the CSV to make them easy to work with:

Field Type	How It Appears in CSV	Example
Text fields	Plain text	Summer Collection
Numbers	The number	42
Boolean (Yes/No)	Yes or No	Yes or No
Dates	Standard date format	2026-03-12
Date and time	ISO format with time	2026-03-12T14:30:00
References (product, metaobject, etc.)	Item name, then ID	Summer Tee | gid://shopify/Product/123456
Lists	Items separated by pipes	Red | Blue | Green
Rich text	Plain text only	This is a summary
JSON	Compact format	{"key":"value"}

Filename format

Your CSV file is automatically named with the definition type, number of entries exported, and the current date.

Example: products_12_entries_2026-03-12.csv

Excel compatibility

The CSV file is saved with UTF-8 BOM encoding, which means it opens correctly in Excel and Google Sheets without any import dialogs or extra steps. Just open the file and it will display properly.

Exporting step by step

1. In the bulk editor, click the Export CSV button.
2. Your browser downloads the file automatically.
3. Open it in Excel, Google Sheets, or your preferred spreadsheet application.
4. The spreadsheet contains all your entries with columns for each field.

Definition Export

A definition export saves the structure (or "schema") of your metaobject definition as a JSON file. This is not your data — it's the blueprint that describes what fields exist, what types they are, and how they're configured.

Definition exports are useful for:

• Backing up your definition structure — save a copy of how you've set up your fields
• Sharing definitions — send the JSON file to a colleague who can import it into their Shopify store
• Version control — keep track of how your definition changes over time

In the bulk editor, click the Export Definition button in the top toolbar, next to the CSV export button.

What format is it?

The definition exports as a .json file named after your definition type. For example, products_definition.json.

What's included

• Field keys and names — the internal identifier and display name for each field
• Field types — what kind of information each field stores (text, number, reference, etc.)
• Field descriptions — any notes about what each field is for
• Validations — rules like minimum/maximum lengths or required fields
• Access settings — whether fields are visible on the storefront
• Definition name and description — the name and description of the definition itself

Exporting your definition

1. In the bulk editor, click the Export Definition button.
2. Your browser downloads the JSON file automatically.
3. The file is ready to share, save, or import elsewhere.

Definition Import

You can import a metaobject definition from a JSON file. The import creates a new definition in your store based on the structure in the JSON file. It does not import data (entries) — only the definition structure.

On the definitions page, click the Import Definition button to open the import dialog.

Step 1: Upload the JSON file

Click the upload area and select a .json file from your computer, or drag and drop a file onto the upload area. The file should be a definition export from Structa or a properly formatted JSON file with the definition structure.

Step 2: Review and configure

After uploading, you'll see:

• Definition name — you can edit this (it's what appears in your admin)
• Definition type — a unique identifier (auto-generated from the name, but you can change it)
• Description — optional notes about the definition
• Fields preview — a list of all the fields that will be imported

Step 3: Fix any conflicts

If the type you're trying to create already exists in your store, you'll see an error message with a suggested alternative name. Either change the type to the suggested alternative or choose a completely different type.

Step 4: Complete the import

Click the Import definition button to create the definition. You'll see a confirmation message and can immediately navigate to the new definition to start creating entries.

After import

• A new definition is created with the structure from the JSON file.
• The definition is immediately available in your metaobject editor.
• All fields, validations, and settings from the JSON are applied.
• You can start creating entries right away.

Important limitations

• No data is imported — only the definition structure, not the actual entries
• Handle is auto-generated — the definition's internal identifier is automatically created and cannot be changed
• Must be unique — the definition type must be unique in your store (no duplicates allowed)

Common Use Cases

Backing up your definitions

1. Click Export Definition for each definition you want to back up.
2. Save the files to a safe location.
3. Restore them later by importing them back.

Exporting data for a spreadsheet

1. Go to the bulk editor for a definition.
2. Click Export CSV.
3. Open the file in your spreadsheet application.
4. Edit, analyze, or share the data as needed.

Duplicating a definition across stores

1. In the source store, click Export Definition.
2. Download the JSON file.
3. Go to the destination store's Structa app.
4. Click Import Definition.
5. Upload the JSON file and complete the import.

Sharing definition structure with your team

1. Export the definition as JSON.
2. Share the file via email or your team's file sharing system.
3. Colleagues can import it to see the exact structure and field setup.

Troubleshooting

The export button is disabled

The export button is disabled when you haven't selected a definition yet, there are no entries to export, or the system is currently saving changes. Select a definition first, or wait for any saves to complete.

CSV file opened in a strange format

This shouldn't happen — the CSV is designed to work with Excel and Google Sheets automatically. If you're having issues, try a different spreadsheet application or make sure you're opening the file directly (not copying the contents).

Error when importing a JSON file

Common reasons:

• The file is not valid JSON (check the formatting)
• The file is missing required fields like name, type, or fieldDefinitions
• The definition type already exists in your store
• The file is not a definition export from Structa

Try using a definition export from the app (via Export Definition), checking that the JSON file is properly formatted, or using a different name or type.

Imported a definition but data didn't come with it

This is expected. Definition import only copies the structure, not the entries. To move entry data:

1. Export the entries as CSV from the source store.
2. Import the definition into the destination store.
3. Use the CSV as a reference to recreate entries manually in the bulk editor.

Can I edit fields after importing?

Yes. After importing a definition, you can edit field names, descriptions, and validations, add or remove fields, and change field types. Go to the definition page and use the Manage Definition option to make changes.

Best Practices

• Regular backups — export your definitions periodically as JSON files
• Filter before exporting — if you have many entries, use filters to export manageable batches
• Label your exports — use descriptive filenames when saving JSON so you remember what each definition is
• Test imports — when importing a definition to a live store, consider testing in a development store first
• Keep CSV files organized — store exported CSV files with meaningful names and dates for easy reference