Metaobjects

A Metaobject is a single record of a Metaobject definition - one instance of the custom object type you declared. If the definition size_guide is the blueprint, then “Men’s shoes EU sizing” is a metaobject built from it.

Each metaobject belongs to a definition, has a handle (a unique, human-friendly slug within its type), a status, an optional displayName, and a set of fields - the values for the definition’s fieldDefinitions.

The Metaobject object

Property	Type	Required	Description
createdAt	string	-	The date and time when the resource was created (ISO 8601 format).
definition	string | null	-	The MetaobjectDefinition (IRI) this metaobject is a record of. Requires the metaobjects:read scope. Returned null when the scope is missing.
displayName	string | null	-	The human-readable label, derived from the field named by the definition's displayNameField.
fields	EmbeddedMetaobjectFieldResource[]	-	The field values of the metaobject, one entry per field definition.
Show fields fields Property Type Required Description key string - The field key (matches a field definition key). metaobject Metaobject[] - The referenced metaobject(s). Populated when ?expand=metaobject is requested. Requires the metaobjects:read scope. Returned empty when the scope is missing. Show metaobject fields Property Type Required Description createdAt string - The date and time when the resource was created (ISO 8601 format). definition string | null - The MetaobjectDefinition (IRI) this metaobject is a record of. Requires the metaobjects:read scope. Returned null when the scope is missing. displayName string | null - The human-readable label, derived from the field named by the definition's displayNameField. fields EmbeddedMetaobjectFieldResource[] - The field values of the metaobject, one entry per field definition. handle string - The metaobject's unique slug within its definition type. id string - The resource's unique identifier (UUID). status "DRAFT" | "ACTIVE" - The publication status of the metaobject. updatedAt string - The date and time when the resource was last modified (ISO 8601 format). type "/api/metafield_definition_types/single_line_text_field" | "/api/metafield_definition_types/multi_line_text_field" | "/api/metafield_definition_types/number_integer" | "/api/metafield_definition_types/number_decimal" | "/api/metafield_definition_types/json" | "/api/metafield_definition_types/list__single_line_text_field" | "/api/metafield_definition_types/list__number_integer" | "/api/metafield_definition_types/list__number_decimal" | "/api/metafield_definition_types/list__product_reference" | "/api/metafield_definition_types/list__media_reference" | "/api/metafield_definition_types/product_reference" | "/api/metafield_definition_types/media_reference" | "/api/metafield_definition_types/metaobject_reference" | "/api/metafield_definition_types/list__metaobject_reference" - The field data type, as an IRI to the field-type resource. value string | null - This property supports translations. The field value, stored as a string regardless of the field type.
handle	string	-	The metaobject's unique slug within its definition type.
id	string	-	The resource's unique identifier (UUID).
status	"DRAFT" | "ACTIVE"	-	The publication status of the metaobject.
updatedAt	string	-	The date and time when the resource was last modified (ISO 8601 format).

Two ways to fetch one

Metaobjects have a normal id-based route, plus a friendly type + handle lookup:

• by id - GET /api/metaobjects/{id}
• by handle - GET /api/metaobjects/{type}/{handle}, useful when you know the slug but not the id.

You can also list every record of one type.

Common workflows

• Add a record. Create a metaobject referencing its definition, with a handle and the fields values. Each value is validated against the definition’s field types.
• Look it up by slug. Use the type + handle route when you reference records by a stable, readable key.
• Reference it. Point a Metafield (whose definition type is a metaobject reference) at a metaobject to attach it to a product or variant.

Conventions

Authentication and headers

All requests require an OAuth 2.0 bearer token:

Authorization: Bearer <token>

Partial updates

PATCH uses JSON Merge Patch with Content-Type: application/merge-patch+json.