# Metafields

> A Metafield is the value of a metafield definition stored on a specific owner record.

A **Metafield** is the **value** of a [Metafield definition](/api/product-management/metafield-definitions/) 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

## Common workflows

- **Set a value.** Create a metafield under an owner, referencing the [definition](/api/product-management/metafield-definitions/) 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](https://datatracker.ietf.org/doc/html/rfc7396) with `Content-Type: application/merge-patch+json`.