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
id	string	-	The resource's unique identifier (UUID).
type	string	required	The unique slug identifier for this metaobject definition.
name	string	required	The human-readable name of the metaobject definition.
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 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. description string | null - An optional description of the field. type string required The field data type, as an IRI to the field-type resource. required boolean - Whether a value for this field is required on metaobjects of the definition. validations EmbeddedMetaobjectFieldDefinitionValidationResource[] - The validation rules applied to values of this field. Show validations fields Property Type Required Description name string required The type of validation rule value string required The validation parameter value. Format depends on the validation type.
createdAt	string	-	The date and time when the resource was created (ISO 8601 format).
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).
• 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 and the organization scope header:

Authorization: Bearer <token>
X-Flowkiwi-Organization-Id: <organization-id>

Partial updates

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