Metafields

A Metafield is the value of a Metafield definition on a specific record - for example the care_instructions of one product. Where the definition is the schema (key, type, validations), the metafield is the data.

Metafields are nested under their owner, so every endpoint is scoped to a {ownerResource} and {ownerId}:

/rest/api/{ownerResource}/{ownerId}/metafields

• ownerResource is the owner’s collection, such as products or variants - it must match the definition’s ownerType.
• ownerId is that record’s id.

For example, the metafields of product 019af93e-... live at /rest/api/products/019af93e-.../metafields.

The Metafield object

Property	Type	Required	Description
id	string	-	The resource's unique identifier (UUID).
value	string	-	This property supports translations. The data stored in the metafield. Always stored as a string, regardless of the metafield's type.
ownerId	string | null	-	The id of the owner record the metafield is attached to.
definition	string	-	The MetafieldDefinition this metafield is an instance of.
ownerResource	string	required	The type of resource that the metafield is attached to.
metaobject	string[]	-	The referenced metaobject(s). Populated when ?expand=metaobject is requested and the field type is metaobject_reference or list__metaobject_reference.
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).

Common workflows

• Set a value. Create a metafield under an owner, referencing the definition and giving it a value. The value is validated against the definition’s type and validations.
• Read a record’s custom data. List the metafields under an owner to get every custom value it carries.
• Reference a metaobject. When the definition’s type is a metaobject reference, the metafield’s metaobject is populated with the referenced record(s).

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>

The value can be translatable, so set the active locale (and optionally a fallback) when reading or writing:

X-Flowkiwi-Locale: fr-FR
X-Flowkiwi-Locale-Fallback: en-US

Partial updates

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