Metaobject definitions

A Metaobject definition declares a brand-new object type of your own - something that doesn’t exist as a built-in resource. Where a Metafield definition adds one field to an existing record (a product, a variant), a metaobject definition describes a whole structured record: a set of fieldDefinitions, each with its own key, type and validations.

Think of it as defining a content type. A “Size guide”, an “Author”, an “Ingredient” - none of these are products, but you may want to model them once and reuse them. The definition is the blueprint; the actual records are Metaobjects built from it.

Each definition has a type (a unique slug such as size_guide), a name, an optional displayNameField (which field to show as a record’s label), and its fieldDefinitions.

The Metaobject definition object

Property	Type	Required	Description
createdAt	string	-	The date and time when the resource was created (ISO 8601 format).
description	string | null	-	The description of the metaobject definition.
displayNameField	string | null	-	The key of the field definition used as the display name for records of this type. Optional - when omitted it is null and records have no derived display name. When set, it must match the key of one of this definition's fieldDefinitions, otherwise the request is rejected with 422.
fieldDefinitions	EmbeddedMetaobjectFieldDefinitionResource[]	-	The field definitions that make up this metaobject definition.
Show fieldDefinitions fields Property Type Required Description description string | null - An optional description of the field. id string - The resource's unique identifier (UUID). key string required The field key, unique within the definition (referenced by metaobject fields). name string required The human-readable name of the field. required boolean - Whether a value for this field is required on metaobjects of the definition. 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" required The field data type, as an IRI to the field-type resource. Immutable once the field definition exists: a PATCH changing it is rejected with a 422. Delete the field and add the key back to use another type. validations EmbeddedMetafieldDefinitionValidationResource[] - The validation rules applied to values of this field. Show validations fields Property Type Required Description name "/api/metafield_definition_validation_types/min_length" | "/api/metafield_definition_validation_types/max_length" | "/api/metafield_definition_validation_types/min_value" | "/api/metafield_definition_validation_types/max_value" | "/api/metafield_definition_validation_types/max_precision" | "/api/metafield_definition_validation_types/json_schema" | "/api/metafield_definition_validation_types/media_type" | "/api/metafield_definition_validation_types/metaobject_definition" required The type of validation rule value string required The validation parameter value. Format depends on the validation type.
id	string	-	The resource's unique identifier (UUID).
name	string	required	The human-readable name of the metaobject definition.
type	string	required	The unique slug identifier for this metaobject definition.
updatedAt	string	-	The date and time when the resource was last modified (ISO 8601 format).

How it fits together

1. Define the type here - its type slug and fieldDefinitions.
2. Create Metaobjects of that type - one record per entry, each with a handle and field values.
3. Reference those records from a product or variant through a Metafield whose definition type is a metaobject reference.

Common workflows

• Model a content type. Create a definition with the fieldDefinitions your records need, then add metaobjects for it.
• Pick a label. Set displayNameField to the field key that best identifies a record (for example a title field).
• Count the records. In the unstable version, list the entry counts of every definition in a single call.
• Evolve it. Patch the definition to add or adjust fieldDefinitions as your model grows.

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.