Metaobject support

Garnet supports Shopify metaobjects as a specification type. Metaobjects are structured content entries managed in Shopify (e.g. artists, exhibitions, press releases) that vendors can reference from their products.

There are two ways metaobjects work with specifications:

Type	Specification type	Use case	Vendor experience
Reference	metaobject_reference	Link a product to one entry	Search modal with thumbnails
Variant	list.metaobject_reference	Link a product to multiple entries as variants	Checkbox picker, creates product variants

Metaobject reference (single)

A metaobject reference lets the vendor pick one metaobject entry per product. This is useful for linking a product to an artist, a collection, a brand, or any entity managed as a Shopify metaobject.

How it works

1. The admin creates a metaobject definition in Shopify (e.g. artist with fields: name, biography, nationality)
2. The admin adds a specification of type Metaobject in Garnet > Admin Panel > Specifications
3. The admin selects which metaobject type to use from the dropdown
4. When uploading a product, vendors see a search modal where they can pick an entry

Admin options

When configuring a metaobject specification, the admin has the following options:

Option	Description	Stored as
Metaobject type	Which metaobject definition to use	metaobject_definition_id validation
Vendor can add entries	Allow vendors to create new entries from the picker	mo_allow_write:true in description
Only show active entries	Filter the list to active entries only	mo_show_status:active in description

Creating entries from the picker

When Vendor can add entries is enabled, the picker modal shows an "Add entry" button. Clicking it opens a form with all the fields from the metaobject definition. The vendor fills in the fields and clicks "Create". The new entry is immediately available and selected.

Image and file fields are supported -- vendors can upload images directly from the form.

Vendor-scoped entries

If the metaobject definition has a field of type metaobject_reference that references the vendor metaobject definition (the app--vendors type used by Garnet to store vendor profiles), then:

• Vendors only see their own entries: the list is automatically filtered to entries linked to the current vendor
• New entries are auto-linked: when a vendor creates an entry, their vendor metaobject ID is automatically set on the vendor field

This enables use cases like vendor-specific exhibitions, where each gallery manages their own exhibitions but the admin can see all of them.

WARNING

The vendor reference field must have the adminFilterable capability enabled in Shopify for vendor-scoped filtering to work. Garnet enables this automatically when it detects a vendor reference field, but if filtering doesn't work, check that the field has adminFilterable enabled in the metaobject definition settings.

Metaobject as variants

A list.metaobject_reference specification links metaobject entries to product variants. This is a Shopify-native feature that lets you define variant options (like size or color) as metaobjects rather than free text.

How it works

1. The admin creates a metaobject definition in Shopify (e.g. shoe_size with a label field)
2. The admin creates metaobject entries for each option (e.g. "EU 38", "EU 39", "EU 40")
3. In Shopify, the admin links the metaobject definition to the product's variant options
4. The admin adds a specification of type Variant field (list.metaobject_reference) in Garnet

When a vendor uploads a product:

• They see a checkbox picker with all available metaobject entries
• Each selected entry becomes a product variant
• Shopify automatically generates variant combinations if multiple variant fields are used
• The metafield value stores the list of selected metaobject IDs

Difference with regular reference

Feature	Reference (metaobject_reference)	Variant (list.metaobject_reference)
Selection	Single entry	Multiple entries
Creates variants	No	Yes
UI component	Search modal	Checkbox picker
Vendor can add entries	Yes (if enabled)	No
Use case	Link to artist, brand, category	Size options, color options

Setting up metaobjects in Shopify

Before using metaobject specifications in Garnet, you need to create the metaobject definition in Shopify:

1. Go to Shopify Admin > Settings > Custom data > Metaobject definitions
2. Click Add definition
3. Set a name (e.g. "Artist") and type (e.g. artist)
4. Add field definitions (name, biography, image, etc.)
5. Set the display name key to the field that should represent each entry (usually name)

INFO

Garnet automatically discovers all metaobject definitions on your store. Internal definitions (prefixed with app--, garnet-, or shopify--) are filtered out from the admin dropdown.

Customizing display name and thumbnail

Garnet uses two Shopify settings to control how entries appear in the picker:

• Display name: controlled by the Entry title setting in Shopify Admin > Settings > Custom data > Metaobject definitions > [your type]. Choose which field represents each entry (e.g. name for artists, title for exhibitions).
• Thumbnail image: Shopify automatically uses the first image field as the thumbnail. To change it, reorder the fields in the metaobject definition so the desired image field comes first, or set the thumbnail field in the definition settings.