1. Overview

The Metaobjects Template is a structured spreadsheet used to import or update metaobjects into your Shopify store via BulkFlow. Metaobjects are custom data entries (like lookbooks, brand guides, size charts) that extend Shopify's native capabilities. BulkFlow allows you to manage these entries in bulk with standardized formatting.

2. Requirements

Make sure you have:

• Downloaded the correct Metaobjects Template from BulkFlow
• A clear understanding of your Metaobject Definitions already set up in Shopify
• Connected your Shopify store to BulkFlow

NOTE: You must define the Metaobject structure (definitions and fields) in Shopify before importing. Otherwise, Shopify may treat them as unstructured and may not save your data properly.

3. How to Fill the Metaobjects Template

Step 1: Create your Metaobject Definition in Shopify

Before filling out the template, you'll need to create your metaobject definition directly in your Shopify admin.
To do this, log in to your Shopify Admin and navigate to Settings → Metafields and metaobjects. Scroll down to the Metaobject definitions block, then click Add definition to begin creating a new metaobject structure.
Once the definition is saved, note down two things you will need for your file:

• The Type shown under the definition name (e.g. beekeeper_profile). This is the value that goes in the Definition: Handle column.
• The Key of each field. Open the definition, expand a field, and read the Key line at the bottom right (e.g. website). The Key is what goes in the Field column — not the display label you see on screen.

For detailed steps, you can also refer to Shopify's official guide on creating metaobject definitions.

Step 2: Download the Metaobjects Template

From the BulkFlow Dashboard, click on Download Template. A dropdown menu will appear — choose the option labeled Metaobjects Template.

Step 3: Fill in the Required Fields

NOTE: A metaobject entry with multiple fields needs multiple rows — one row per field. Repeat the same Handle and Definition: Handle on every row so BulkFlow knows they belong to the same entry.
For example, to create one "peter-bloom" entry with a title, description, and website, you'd add three rows — all with Handle = peter-bloom, but a different Field and Value on each row.

Specific case: reference fields

Most field types take a plain value. Reference fields are the exception — if a field points to another metaobject, a product, or a file, the Value must be the GID of the target, not its handle. BulkFlow does not convert handles into GIDs for you.
The format is gid://shopify/Metaobject/<ID> — for example gid://shopify/Metaobject/55642134.
The <ID> part is the Shopify ID of the entry you are pointing to. You can read it directly from that entry in your Shopify admin, or export all your metaobjects from BulkFlow and take it from the ID column.
Two things to keep in mind:

• The entry you reference must already exist before you import the entry that points to it. If both sides come from your own files, import the referenced entries first, collect their IDs, then build and import the second file.
• A field that accepts one value takes a single bare GID. A field that accepts a list takes a JSON array — for example ["gid://shopify/Metaobject/111","gid://shopify/Metaobject/222"].

Step 4: Save the File in the Correct Format

• File Upload: Save your file as XLSX or CSV (UTF-8) and upload it manually.
• Google Sheet: Use a shared Google Sheet link.
• File URL: Use a direct URL to connect your file.
• Google Drive: Use a shared Google Drive link.
• FTP/SFTP: You can also upload via FTP or SFTP.
• Dropbox: Use a shared Dropbox link.
• One Drive: Use a shared One Drive link.

Step 5: Run a Demo, Then Process Your Metaobject Feed

• Click Demo Import to run the feed on a small sample of your data and preview the result before committing to anything.
• Once you're satisfied with the preview, click Full Import to process the entire feed.
• You can check the result and download it to see which entries were successfully imported and which were not.
• If some rows failed, correct them in your file and then click Clear Failed Items in the Results section before running the feed again. Without this step, the system will skip those rows on the next run.

4. Tips

• You must create the Metaobject Definition in Shopify before importing.
• Each metaobject entry needs one row per field — repeat the same Handle and Definition: Handle across all its rows.
• Each Handle must be unique per metaobject type.
• Handles accept lowercase letters, numbers and hyphens only.
• Be careful when re-running an import feed. If the ID column is blank and the Handle already exists, Shopify will not report an error — it creates a new entry and adds a suffix to the handle, so you end up with solterra, solterra-1, solterra-2. To change entries that already exist, fill in the ID column and run an Update feed instead of importing again.

5. FAQs

1. What happens if I use an undefined metaobject type?

Shopify will reject the data or treat it as unstructured. Always define the metaobject in Shopify admin first.

2. What if the Field value I enter doesn't match any field in my Metaobject Definition?

BulkFlow will not be able to match it, and the row will fail with a formatting error. Make sure the Field value exactly matches a field key defined in your Metaobject Definition in Shopify.

Updated on: 24/09/2026