> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://bulkflow.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# How to fill in the Metaobjects Template

# 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__](https://help.shopify.com/en/manual/custom-data/metaobjects) 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
| **Column** | **Required** | **Description** | **Value Format & Example** |
| ---- | ---- | ---- | ---- |
| **ID** | No | The Shopify Metaobject ID. Leave blank when creating new entries with an Import feed — Shopify will generate it automatically. Required when using an Update feed, to match the existing entry you want to update. You can get an ID by opening the entry in your Shopify admin, or by exporting all your metaobjects from BulkFlow and reading the **ID** column. | Eg: 55642134 |
| **Handle** | Yes | Unique identifier/slug for the metaobject entry. Use the **same Handle on every row** that belongs to the same entry. Use **lowercase letters, numbers and hyphens only** — uppercase letters, spaces and special characters such as `#` or `.` will make the row fail. | Valid: peter-bloom, smart-5, volkswagen-id-7. Invalid: Peter-Bloom, smart-#5, volkswagen-id.7 |
| **Status** | Yes | The current state of the Metaobject entry. | Active or Draft — Eg: Active |
| **Definition: Handle** | Yes | The **Type** of the Metaobject Definition this entry belongs to, exactly as shown in your Shopify admin. Watch out for singular vs plural — `car_model` and `car_models` are different values. | Eg: beekeeper_profile |
| **Field** | Yes | The **Key** of the field being set, as defined in your Metaobject Definition — not the display label. Each row sets **one** field. | Eg: title, description, website, rating |
| **Value** | Yes | The value for that field. For structured field types like rating, the value may be a JSON object. | Eg: Peter Bloom. For rating: {"scale_min":"0.0","scale_max":"5.0","value":"4.5"} |

**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.