Metaobjects

The Metaobjects settings allow you to build complex, structured data models for your store. While standard Metafields are used to store a single piece of information (like "Fabric Type" for a product), Metaobjects allow you to group multiple pieces of information together to create a completely new resource type that fits your specific business needs.

Location: Content → MetaObjects

---

What Are Metaobjects?

Metaobjects are custom data structures that let you group multiple fields together into a single, reusable content type. While metafields store one value at a time, metaobjects bundle related information — like a name, photo, and biography — into a cohesive unit.

• Multi-Field Structures - Combine text, images, dates, and more into one content type
• Reusable Entries - Create once, reference from many products or pages
• Custom Content Types - Build completely new resource types like profiles, locations, or lookbooks

For Store Owners

Think of Metaobjects as custom forms you design yourself. For example, a "Designer Profile" form with fields for Name, Bio, and Photo — then fill it out for each designer and link them to products.

---

Metaobjects Overview

When you open Content → MetaObjects, you land on the Metaobjects dashboard. This page lists all existing Metaobject definitions and provides tools to search, filter, and manage them.

Dashboard Elements

• Search bar: Search metaobject definitions by name
• Add filter: Filter definitions by public access
• Sort control: Sort definitions by ID, Name, Created, or Updated
• Add Metaobject button: Creates a new metaobject definition

Definitions Table

The table displays:

• Name – Metaobject definition name
• Fields – Number of fields in the definition
• Entries – Number of entries created
• Action – Entry management actions

---

Quick Start Guide

If you're setting up metaobjects for the first time, follow these steps:

1. Plan your content type — Decide what information to group (e.g., "Designer Profile" with Name, Bio, Photo)
2. Create a definition — Build the blueprint with the fields you need
3. Add entries — Fill in actual data for each instance (e.g., each designer)
4. Connect to products — Link entries to products via a Metafield reference
5. Display on storefront — Connect to your theme via the Theme Editor

For detailed instructions, continue reading below.

---

When Should You Use Metaobjects?

Use Metaobjects when:

• You need reusable structured content
• Multiple products share the same data
• Data contains more than one field
• You want relational content (profiles, lookups)

Use Metafields when:

• Data belongs to one product only
• The value is simple (single attribute)

---

Metafields vs. Metaobjects

It is important to understand which tool to use for your specific goal.

Feature	Metafields	Metaobjects
Structure	Stores a single value.	Stores multiple grouped values.
Best For	Simple attributes (e.g., "Wash Care", "Release Date").	Complex entities (e.g., "Author Profile", "Store Location", "Lookbook").
Connection	Attached directly to a specific product or page.	Can be created once and referenced by many different products.

Analogy

If a Metafield is a single sticky note on a file folder, a Metaobject is a completely new form inside that folder containing a Name, a Photo, a Date, and a Signature all together.

---

Creating a Definition (The Blueprint)

To use Metaobjects, you must first define what the object "is." This is called the Definition.

Example Scenario: Creating a "Designer Profile".

1. Click button at the top-right.
2. Name: Enter a descriptive label (e.g., Designer Profile).
3. Add Fields: A Metaobject needs fields to store data. Click + Add Field and configure the settings below.

Field Configuration Settings

Setting	Description
Name	The label users see when entering data (e.g., Designer Name).
Key	The system ID used by APIs and Developers. Important: This cannot be edited after creation.
Select Type	Defines the data format. Options include: • Text: (Single or Multiline) • Numeric: (Numbers or Prices) • Date: (Calendar) • Visual: (Color picker or Image) • Reference: (Link to other content)

Repeat the "Add Field" step until your structure is complete (e.g., Name + Bio + Photo).

Access Control

At the bottom of the definition page, set the Public Access:

• Enabled: The data is exposed to the Storefront API (visible to themes/apps).
• Disabled: The data is strictly for internal Admin use.

Click button to finalize the blueprint.

---

Adding Entries (The Data)

Now that you have created the "Form" (Definition), you need to fill it out with actual content.

1. Navigate to the MetaObjects list page.
2. Locate the definition you want to populate (e.g., Designer Profile).
3. In the Action column on the far right, click the Entries link.
4. You will be taken to the specific list of entries for that object.
5. Click the button at the top-right.
6. A form will open displaying the specific fields you defined earlier. Fill in the data:
   • Designer Name: "Jane Doe"
   • Bio: "Jane has 20 years of experience..."
   • Photo: [Upload Image]
7. Click the button.

Reusability

You can repeat these steps to add unlimited entries (e.g., Jane Doe, John Smith, Alice Brown) all using the same Designer Profile structure.

---

Filtering and Sorting

• Filter: Use the Public filter to show only public or private metaobjects.
• Sorting: Use the sort menu to order metaobjects by:
  • ID
  • Name
  • Created date
  • Updated date
  • Ascending or Descending order

---

Managing Definitions & Fields

You can modify your structure at any time, but be aware of data limitations.

Editing Fields

Click on any field row inside the Definition to update it.

• Allowed: You can change the Name or Public Access.
• Not Allowed: You cannot change the Key or Content Type (e.g., changing "Text" to "Image").

Deleting Fields

To remove a specific field (like "Bio") from the structure:

1. Locate the field row you want to remove.
2. Click the Delete icon
   .

Irreversible Action

Deleting a field will immediately remove that specific data point from every single entry you have created. This action cannot be undone.

Deleting the Entire Metaobject

To delete the entire structure:

1. Scroll to the bottom of the definition page.
2. Click the button.
3. Confirm: A modal will appear to verify your decision. Click the button inside the modal to finalize the action.

Critical Warning

Deleting a Metaobject definition destroys the Blueprint AND all data entries associated with it. This action is immediate and cannot be undone.

---

How to Connect to Products (Advanced Usage)

Metaobjects are powerful because they are reusable. The most common way to use them is to link them to a Product.

Step 1: Create a Reference Field

1. Go to Content → Metafields → Product.
2. Click Add Metafield.
3. Name: Assigned Designer.
4. Select Type: Choose Metaobject.
5. Reference: Select your Designer Profile object from the list.
6. Save.

Step 2: Link the Data

1. Go to a specific Product (e.g., "Summer Dress").
2. Scroll to the bottom Metafields section.
3. Click Assigned Designer.
4. Select Entry: A list of your designers (Jane Doe, John Smith) will appear. Pick one.
5. Save.

Now, the "Summer Dress" product is officially linked to the "Jane Doe" profile.

---

Real World Examples

To help you understand how metaobjects work in practice, here are common use cases.

Example 1: Designer Profiles

Goal: Create reusable designer profiles that can be linked to multiple products.

Definition:

Field	Type
Designer Name	Text (Single line)
Bio	Text (Multiline)
Photo	Image
Years of Experience	Number

Entries: Jane Doe, John Smith, Alice Brown

Connection: Create a "Assigned Designer" Metafield on Products → Reference the Designer Profile Metaobject → Select a designer for each product.

Why this works:

• One profile, many products — update the designer bio once and it updates everywhere
• Standardized structure ensures consistency across all designer pages

Example 2: Store Locations

Goal: Build a structured "Store Location" content type for a store locator page.

Definition:

Field	Type
Store Name	Text (Single line)
Address	Text (Multiline)
Store Photo	Image
Opening Hours	Text (Multiline)
Phone	Text (Single line)

Entries: Each physical store location as a separate entry.

Why this works:

• Structured data makes it easy to render a consistent store locator page
• Adding a new store is as simple as adding a new entry

Example 3: Product Lookbook

Goal: Create curated lookbook entries with styled images and descriptions.

Definition:

Field	Type
Lookbook Title	Text (Single line)
Description	Text (Multiline)
Hero Image	Image
Season	Text (Single line)

Entries: "Summer 2026", "Winter Collection", "Street Style"

Why this works:

• Lookbooks can be referenced by multiple products
• Seasonal content can be managed centrally and rotated easily

---

Troubleshooting

Common issues and how to fix them:

I can't find my metaobject entries

Possible causes:

• You're looking at the Definitions list, not the Entries list

Solution:

1. Go to Content → MetaObjects
2. Find your definition in the list
3. Click the Entries link in the Action column on the right
4. This opens the entries list for that specific metaobject

My metaobject data isn't showing on the product page

Possible causes:

• The metaobject isn't connected to the product via a Metafield reference
• Public Access is disabled on the metaobject definition

Solution:

1. Create a Metafield on the Product resource with type "Metaobject"
2. Reference the correct Metaobject definition
3. Go to the product and select an entry in the Metafields section
4. Ensure Public Access is enabled on both the Metafield and Metaobject
5. Connect the data to a theme block via the Theme Editor

I accidentally deleted a field and lost data

Possible causes:

• Field deletion is immediate and permanent

Solution:

1. Unfortunately, deleted field data cannot be recovered
2. Re-add the field to the definition with the same name and type
3. Manually re-enter the data for each entry
4. To prevent future data loss, document your metaobject structures before making changes

I can't change a field's type after creation

Possible causes:

• Field Key and Content Type are locked after saving by design

Solution:

1. Add a new field with the correct type
2. Copy data from the old field to the new one for each entry
3. Delete the old field once all data is migrated

Need More Help?

If you're still experiencing issues, contact Soppiya support with the metaobject name, field configuration, and a screenshot of your setup.

---

Best Practices

Metaobject Management Best Practices

Planning

• Design before building: Sketch out all the fields you need before creating the definition — field types can't be changed later
• Use Metaobjects vs. Metafields wisely: If data has more than one field and is shared across items, use a Metaobject. If it's a single value per item, use a Metafield
• Name clearly: Use descriptive definition names like "Designer Profile" instead of vague names like "Profile"

Data Management

• Keep entries consistent: Fill in all fields for every entry to maintain data quality
• Set Public Access appropriately: Enable it only when the storefront needs to display the data
• Document your structures: Maintain a list of metaobject definitions, their fields, and which products reference them

Common Mistakes to Avoid

• ❌ Deleting fields without checking entries — all data for that field is permanently erased
• ❌ Creating metaobjects for single-value data — use Metafields instead
• ❌ Forgetting to link entries to products — creating the definition and entries isn't enough, you need a reference Metafield
• ❌ Using the same field name across different definitions — this can cause confusion when connecting to products

---

Summary

Metaobjects let you build custom, structured content types that go beyond simple single-value fields. They're ideal for reusable, multi-field data like profiles, locations, and lookbooks.

Key takeaways:

• Metaobjects group multiple fields into a single content type (definition)
• Each definition can have unlimited entries (individual data records)
• Entries are reusable — link one entry to many products via Metafield references
• Field Key and Content Type are permanent once saved — plan carefully
• Set Public Access to control storefront visibility
• Deletion of definitions or fields is permanent and erases all associated data

If you're just getting started, create a simple Metaobject with 2-3 fields (like a "Brand Profile" with Name and Logo), add one entry, link it to a product, and test the full workflow before building more complex structures.