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
id	string	-	The resource's unique identifier (UUID).
definition	string	-	The MetaobjectDefinition (IRI) this metaobject is a record of.
handle	string	-	The metaobject's unique slug within its definition type.
status	"DRAFT" | "ACTIVE"	-	The publication status of the metaobject.
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). value string | null - The field value, stored as a string regardless of the field type. type string - The field data type, as an IRI to the field-type resource. metaobject Metaobject[] - Show metaobject fields Property Type Required Description id string - The resource's unique identifier (UUID). definition string - The MetaobjectDefinition (IRI) this metaobject is a record of. handle string - The metaobject's unique slug within its definition type. status "DRAFT" | "ACTIVE" - The publication status of the metaobject. 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. 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).
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).

Two ways to fetch one

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

• by id - GET /rest/api/metaobjects/{id}
• by handle - GET /rest/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 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.