# Metaobjects

> A Metaobject is a record of a metaobject definition - one instance of your custom object type.

A **Metaobject** is a single **record** of a [Metaobject definition](/api/product-management/metaobject-definitions/) - 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

## 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}`](/api/product-management/metaobjects/retrieve/)
- by handle - [`GET /rest/api/metaobjects/{type}/{handle}`](/api/product-management/metaobjects/retrieve-by-handle/), useful when you know the slug but not the id.

You can also [list every record of one type](/api/product-management/metaobjects/list-by-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](/api/product-management/metafields/) (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](https://datatracker.ietf.org/doc/html/rfc7396) with `Content-Type: application/merge-patch+json`.