---
title: Metafields
description: The API for interacting with metafields.
api_version: 2025-01
api_name: checkout-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/checkout-ui-extensions/2025-01/apis/metafields
  md: https://shopify.dev/docs/api/checkout-ui-extensions/2025-01/apis/metafields.md
---

# MetafieldsAPI

Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) for some properties.

The API for interacting with metafields.

## StandardApi

The base API object provided to `purchase` extension targets.

* appMetafields

  StatefulRemoteSubscribable\<AppMetafieldEntry\[]>

  required

  The metafields requested in the [`shopify.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) file. These metafields are updated when there's a change in the merchandise items being purchased by the customer.

  [](https://shopify.dev/apps/store/data-protection/protected-customer-data)Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

  Tip

  \> Metafields on an [app reserved namespace](https://shopify.dev/docs/apps/build/custom-data/reserved-prefixes) cannot be accessed by Checkout UI extensions.

* metafields

  StatefulRemoteSubscribable\<Metafield\[]>

  required

  The metafields that apply to the current checkout.

  Metafields are stored locally on the client and are applied to the order object after the checkout completes.

  These metafields are shared by all extensions running on checkout, and persist for as long as the customer is working on this checkout.

  Once the order is created, you can query these metafields using the [GraphQL Admin API](https://shopify.dev/docs/admin-api/graphql/reference/orders/order#metafield-2021-01)

  Tip

  \> Cart metafields are only available on carts created via the Storefront API version `2023-04` or later.

### AppMetafieldEntry

A metafield associated with the shop or a resource on the checkout.

* metafield

  The metadata information.

  ```ts
  AppMetafield
  ```

* target

  The target that is associated to the metadata. {% include /apps/checkout/privacy-icon.md %} Requires access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data) when the type is \`customer\`, \`company\` or \`companyLocation\`.

  ```ts
  AppMetafieldEntryTarget
  ```

```ts
export interface AppMetafieldEntry {
  /**
   * The target that is associated to the metadata.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.
   */
  target: AppMetafieldEntryTarget;

  /** The metadata information. */
  metafield: AppMetafield;
}
```

### AppMetafield

Represents a custom metadata attached to a resource.

* key

  The key name of a metafield.

  ```ts
  string
  ```

* namespace

  The namespace for a metafield.

  ```ts
  string
  ```

* type

  The metafield's type name.

  ```ts
  string
  ```

* value

  The value of a metafield.

  ```ts
  string | number | boolean
  ```

* valueType

  The metafield’s information type.

  ```ts
  'boolean' | 'float' | 'integer' | 'json_string' | 'string'
  ```

```ts
export interface AppMetafield {
  /** The key name of a metafield. */
  key: string;

  /** The namespace for a metafield. */
  namespace: string;

  /** The value of a metafield. */
  value: string | number | boolean;

  /** The metafield’s information type. */
  valueType: 'boolean' | 'float' | 'integer' | 'json_string' | 'string';

  /** The metafield's type name. */
  type: string;
}
```

### AppMetafieldEntryTarget

The metafield owner.

* id

  The numeric owner ID that is associated with the metafield.

  ```ts
  string
  ```

* type

  The type of the metafield owner. {% include /apps/checkout/privacy-icon.md %} Requires access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data) when the type is \`customer\`, \`company\` or \`companyLocation\`.

  ```ts
  | 'customer'
      | 'product'
      | 'shop'
      | 'shopUser'
      | 'variant'
      | 'company'
      | 'companyLocation'
      | 'cart'
  ```

```ts
export interface AppMetafieldEntryTarget {
  /**
   * The type of the metafield owner.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.
   */
  type:
    | 'customer'
    | 'product'
    | 'shop'
    | 'shopUser'
    | 'variant'
    | 'company'
    | 'companyLocation'
    | 'cart';

  /** The numeric owner ID that is associated with the metafield. */
  id: string;
}
```

### Metafield

Metadata associated with the checkout.

* key

  The name of the metafield. It must be between 3 and 30 characters in length (inclusive).

  ```ts
  string
  ```

* namespace

  A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. This must be between 2 and 20 characters in length (inclusive).

  ```ts
  string
  ```

* value

  The information to be stored as metadata.

  ```ts
  string | number
  ```

* valueType

  The metafield’s information type.

  ```ts
  'integer' | 'string' | 'json_string'
  ```

```ts
export interface Metafield {
  /**
   * The name of the metafield. It must be between 3 and 30 characters in
   * length (inclusive).
   */
  key: string;

  /**
   * A container for a set of metafields. You need to define a custom
   * namespace for your metafields to distinguish them from the metafields
   * used by other apps. This must be between 2 and 20 characters in length (inclusive).
   */
  namespace: string;

  /**
   * The information to be stored as metadata.
   */
  value: string | number;

  /** The metafield’s information type. */
  valueType: 'integer' | 'string' | 'json_string';
}
```

## use​App​Metafields([filters](#useappmetafields-propertydetail-filters)​)

Returns the metafields configured with `shopify.extension.toml`.

### Parameters

* filters

  AppMetafieldFilters

  Default: {}

### Returns

* AppMetafieldEntry\[]

### AppMetafieldFilters

* id

  ```ts
  string
  ```

* key

  ```ts
  string
  ```

* namespace

  ```ts
  string
  ```

* type

  ```ts
  "customer" | "product" | "shop" | "shopUser" | "variant" | "company" | "companyLocation" | "cart"
  ```

```ts
interface AppMetafieldFilters {
  id?: AppMetafieldEntryTarget['id'];
  type?: AppMetafieldEntryTarget['type'];
  namespace?: Metafield['namespace'];
  key?: Metafield['key'];
}
```

### AppMetafieldEntry

A metafield associated with the shop or a resource on the checkout.

* metafield

  The metadata information.

  ```ts
  AppMetafield
  ```

* target

  The target that is associated to the metadata. {% include /apps/checkout/privacy-icon.md %} Requires access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data) when the type is \`customer\`, \`company\` or \`companyLocation\`.

  ```ts
  AppMetafieldEntryTarget
  ```

```ts
export interface AppMetafieldEntry {
  /**
   * The target that is associated to the metadata.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.
   */
  target: AppMetafieldEntryTarget;

  /** The metadata information. */
  metafield: AppMetafield;
}
```

### AppMetafield

Represents a custom metadata attached to a resource.

* key

  The key name of a metafield.

  ```ts
  string
  ```

* namespace

  The namespace for a metafield.

  ```ts
  string
  ```

* type

  The metafield's type name.

  ```ts
  string
  ```

* value

  The value of a metafield.

  ```ts
  string | number | boolean
  ```

* valueType

  The metafield’s information type.

  ```ts
  'boolean' | 'float' | 'integer' | 'json_string' | 'string'
  ```

```ts
export interface AppMetafield {
  /** The key name of a metafield. */
  key: string;

  /** The namespace for a metafield. */
  namespace: string;

  /** The value of a metafield. */
  value: string | number | boolean;

  /** The metafield’s information type. */
  valueType: 'boolean' | 'float' | 'integer' | 'json_string' | 'string';

  /** The metafield's type name. */
  type: string;
}
```

### AppMetafieldEntryTarget

The metafield owner.

* id

  The numeric owner ID that is associated with the metafield.

  ```ts
  string
  ```

* type

  The type of the metafield owner. {% include /apps/checkout/privacy-icon.md %} Requires access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data) when the type is \`customer\`, \`company\` or \`companyLocation\`.

  ```ts
  | 'customer'
      | 'product'
      | 'shop'
      | 'shopUser'
      | 'variant'
      | 'company'
      | 'companyLocation'
      | 'cart'
  ```

```ts
export interface AppMetafieldEntryTarget {
  /**
   * The type of the metafield owner.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.
   */
  type:
    | 'customer'
    | 'product'
    | 'shop'
    | 'shopUser'
    | 'variant'
    | 'company'
    | 'companyLocation'
    | 'cart';

  /** The numeric owner ID that is associated with the metafield. */
  id: string;
}
```

## use​Metafield([filters](#usemetafield-propertydetail-filters)​)

Returns a single filtered `Metafield` or `undefined`.

### Parameters

* filters

  MetafieldFilter

  required

### Returns

* Metafield | undefined

### MetafieldFilter

* key

  ```ts
  string
  ```

* namespace

  ```ts
  string
  ```

```ts
interface MetafieldFilter {
  namespace: string;
  key: string;
}
```

### Metafield

Metadata associated with the checkout.

* key

  The name of the metafield. It must be between 3 and 30 characters in length (inclusive).

  ```ts
  string
  ```

* namespace

  A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. This must be between 2 and 20 characters in length (inclusive).

  ```ts
  string
  ```

* value

  The information to be stored as metadata.

  ```ts
  string | number
  ```

* valueType

  The metafield’s information type.

  ```ts
  'integer' | 'string' | 'json_string'
  ```

```ts
export interface Metafield {
  /**
   * The name of the metafield. It must be between 3 and 30 characters in
   * length (inclusive).
   */
  key: string;

  /**
   * A container for a set of metafields. You need to define a custom
   * namespace for your metafields to distinguish them from the metafields
   * used by other apps. This must be between 2 and 20 characters in length (inclusive).
   */
  namespace: string;

  /**
   * The information to be stored as metadata.
   */
  value: string | number;

  /** The metafield’s information type. */
  valueType: 'integer' | 'string' | 'json_string';
}
```

## use​Metafields([filters](#usemetafields-propertydetail-filters)​)

Returns the current array of `metafields` applied to the checkout. You can optionally filter the list.

### Parameters

* filters

  MetafieldsFilters

### Returns

* Metafield\[]

### MetafieldsFilters

* key

  ```ts
  string
  ```

* namespace

  ```ts
  string
  ```

```ts
interface MetafieldsFilters {
  namespace: string;
  key?: string;
}
```

### Metafield

Metadata associated with the checkout.

* key

  The name of the metafield. It must be between 3 and 30 characters in length (inclusive).

  ```ts
  string
  ```

* namespace

  A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. This must be between 2 and 20 characters in length (inclusive).

  ```ts
  string
  ```

* value

  The information to be stored as metadata.

  ```ts
  string | number
  ```

* valueType

  The metafield’s information type.

  ```ts
  'integer' | 'string' | 'json_string'
  ```

```ts
export interface Metafield {
  /**
   * The name of the metafield. It must be between 3 and 30 characters in
   * length (inclusive).
   */
  key: string;

  /**
   * A container for a set of metafields. You need to define a custom
   * namespace for your metafields to distinguish them from the metafields
   * used by other apps. This must be between 2 and 20 characters in length (inclusive).
   */
  namespace: string;

  /**
   * The information to be stored as metadata.
   */
  value: string | number;

  /** The metafield’s information type. */
  valueType: 'integer' | 'string' | 'json_string';
}
```

## CheckoutApi

The API object provided to `purchase.checkout` extension targets.

* applyMetafieldChange

  (change: MetafieldChange) => Promise\<MetafieldChangeResult>

  required

  Performs an update on a piece of metadata attached to the checkout. If successful, this mutation results in an update to the value retrieved through the [`metafields`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/metafields#standardapi-propertydetail-metafields) property.

  Note

  This method will return an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cart-instructions#standardapi-propertydetail-instructions) `metafields.canSetCartMetafields` is false, or the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.

### MetafieldChange

```ts
MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange
```

### MetafieldRemoveChange

Removes a metafield.

* key

  The name of the metafield to remove.

  ```ts
  string
  ```

* namespace

  The namespace of the metafield to remove.

  ```ts
  string
  ```

* type

  The type of the \`MetafieldRemoveChange\` API.

  ```ts
  "removeMetafield"
  ```

```ts
export interface MetafieldRemoveChange {
  /**
   * The type of the `MetafieldRemoveChange` API.
   */
  type: 'removeMetafield';

  /**
   * The name of the metafield to remove.
   */
  key: string;

  /**
   * The namespace of the metafield to remove.
   */
  namespace: string;
}
```

### MetafieldUpdateChange

Updates a metafield. If a metafield with the provided key and namespace does not already exist, it gets created.

* key

  The name of the metafield to update.

  ```ts
  string
  ```

* namespace

  The namespace of the metafield to add.

  ```ts
  string
  ```

* type

  The type of the \`MetafieldUpdateChange\` API.

  ```ts
  "updateMetafield"
  ```

* value

  The new information to store in the metafield.

  ```ts
  string | number
  ```

* valueType

  The metafield’s information type.

  ```ts
  'integer' | 'string' | 'json_string'
  ```

```ts
export interface MetafieldUpdateChange {
  /**
   * The type of the `MetafieldUpdateChange` API.
   */
  type: 'updateMetafield';

  /** The name of the metafield to update. */
  key: string;

  /** The namespace of the metafield to add. */
  namespace: string;

  /** The new information to store in the metafield. */
  value: string | number;

  /**
   * The metafield’s information type.
   */
  valueType: 'integer' | 'string' | 'json_string';
}
```

### MetafieldRemoveCartChange

Removes a cart metafield.

* key

  The name of the metafield to remove.

  ```ts
  string
  ```

* namespace

  The namespace of the metafield to remove.

  ```ts
  string
  ```

* type

  The type of the \`MetafieldRemoveChange\` API.

  ```ts
  "removeCartMetafield"
  ```

```ts
export interface MetafieldRemoveCartChange {
  /**
   * The type of the `MetafieldRemoveChange` API.
   */
  type: 'removeCartMetafield';

  /**
   * The name of the metafield to remove.
   */
  key: string;

  /**
   * The namespace of the metafield to remove.
   */
  namespace: string;
}
```

### MetafieldUpdateCartChange

Updates a cart metafield. If a metafield with the provided key and namespace does not already exist, it gets created.

* metafield

  ```ts
  { key: string; namespace: string; value: string; type: string; }
  ```

* type

  The type of the \`MetafieldUpdateChange\` API.

  ```ts
  "updateCartMetafield"
  ```

```ts
export interface MetafieldUpdateCartChange {
  /**
   * The type of the `MetafieldUpdateChange` API.
   */
  type: 'updateCartMetafield';

  metafield: {
    /** The name of the metafield to update. */
    key: string;

    /** The namespace of the metafield to add. */
    namespace: string;

    /** The new information to store in the metafield. */
    value: string;

    /**
     * The metafield’s information type.
     * See the [`metafields documentation`](/docs/apps/custom-data/metafields/types) for a list of supported types.
     */
    type: string;
  };
}
```

### MetafieldChangeResult

```ts
MetafieldChangeResultSuccess | MetafieldChangeResultError
```

### MetafieldChangeResultSuccess

* type

  The type of the \`MetafieldChangeResultSuccess\` API.

  ```ts
  "success"
  ```

```ts
export interface MetafieldChangeResultSuccess {
  /**
   * The type of the `MetafieldChangeResultSuccess` API.
   */
  type: 'success';
}
```

### MetafieldChangeResultError

* message

  A message that explains the error. This message is useful for debugging. It is \*\*not\*\* localized, and therefore should not be presented directly to the buyer.

  ```ts
  string
  ```

* type

  The type of the \`MetafieldChangeResultError\` API.

  ```ts
  "error"
  ```

```ts
export interface MetafieldChangeResultError {
  /**
   * The type of the `MetafieldChangeResultError` API.
   */
  type: 'error';

  /**
   * A message that explains the error. This message is useful for debugging.
   * It is **not** localized, and therefore should not be presented directly
   * to the buyer.
   */
  message: string;
}
```

## use​Apply​Metafields​Change()

Returns a function to mutate the `metafields` property of the checkout.

### Returns

* (change: MetafieldChange) => Promise\<MetafieldChangeResult>

### MetafieldChange

```ts
MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange
```

### MetafieldRemoveChange

Removes a metafield.

* key

  The name of the metafield to remove.

  ```ts
  string
  ```

* namespace

  The namespace of the metafield to remove.

  ```ts
  string
  ```

* type

  The type of the \`MetafieldRemoveChange\` API.

  ```ts
  "removeMetafield"
  ```

```ts
export interface MetafieldRemoveChange {
  /**
   * The type of the `MetafieldRemoveChange` API.
   */
  type: 'removeMetafield';

  /**
   * The name of the metafield to remove.
   */
  key: string;

  /**
   * The namespace of the metafield to remove.
   */
  namespace: string;
}
```

### MetafieldUpdateChange

Updates a metafield. If a metafield with the provided key and namespace does not already exist, it gets created.

* key

  The name of the metafield to update.

  ```ts
  string
  ```

* namespace

  The namespace of the metafield to add.

  ```ts
  string
  ```

* type

  The type of the \`MetafieldUpdateChange\` API.

  ```ts
  "updateMetafield"
  ```

* value

  The new information to store in the metafield.

  ```ts
  string | number
  ```

* valueType

  The metafield’s information type.

  ```ts
  'integer' | 'string' | 'json_string'
  ```

```ts
export interface MetafieldUpdateChange {
  /**
   * The type of the `MetafieldUpdateChange` API.
   */
  type: 'updateMetafield';

  /** The name of the metafield to update. */
  key: string;

  /** The namespace of the metafield to add. */
  namespace: string;

  /** The new information to store in the metafield. */
  value: string | number;

  /**
   * The metafield’s information type.
   */
  valueType: 'integer' | 'string' | 'json_string';
}
```

### MetafieldRemoveCartChange

Removes a cart metafield.

* key

  The name of the metafield to remove.

  ```ts
  string
  ```

* namespace

  The namespace of the metafield to remove.

  ```ts
  string
  ```

* type

  The type of the \`MetafieldRemoveChange\` API.

  ```ts
  "removeCartMetafield"
  ```

```ts
export interface MetafieldRemoveCartChange {
  /**
   * The type of the `MetafieldRemoveChange` API.
   */
  type: 'removeCartMetafield';

  /**
   * The name of the metafield to remove.
   */
  key: string;

  /**
   * The namespace of the metafield to remove.
   */
  namespace: string;
}
```

### MetafieldUpdateCartChange

Updates a cart metafield. If a metafield with the provided key and namespace does not already exist, it gets created.

* metafield

  ```ts
  { key: string; namespace: string; value: string; type: string; }
  ```

* type

  The type of the \`MetafieldUpdateChange\` API.

  ```ts
  "updateCartMetafield"
  ```

```ts
export interface MetafieldUpdateCartChange {
  /**
   * The type of the `MetafieldUpdateChange` API.
   */
  type: 'updateCartMetafield';

  metafield: {
    /** The name of the metafield to update. */
    key: string;

    /** The namespace of the metafield to add. */
    namespace: string;

    /** The new information to store in the metafield. */
    value: string;

    /**
     * The metafield’s information type.
     * See the [`metafields documentation`](/docs/apps/custom-data/metafields/types) for a list of supported types.
     */
    type: string;
  };
}
```

### MetafieldChangeResult

```ts
MetafieldChangeResultSuccess | MetafieldChangeResultError
```

### MetafieldChangeResultSuccess

* type

  The type of the \`MetafieldChangeResultSuccess\` API.

  ```ts
  "success"
  ```

```ts
export interface MetafieldChangeResultSuccess {
  /**
   * The type of the `MetafieldChangeResultSuccess` API.
   */
  type: 'success';
}
```

### MetafieldChangeResultError

* message

  A message that explains the error. This message is useful for debugging. It is \*\*not\*\* localized, and therefore should not be presented directly to the buyer.

  ```ts
  string
  ```

* type

  The type of the \`MetafieldChangeResultError\` API.

  ```ts
  "error"
  ```

```ts
export interface MetafieldChangeResultError {
  /**
   * The type of the `MetafieldChangeResultError` API.
   */
  type: 'error';

  /**
   * A message that explains the error. This message is useful for debugging.
   * It is **not** localized, and therefore should not be presented directly
   * to the buyer.
   */
  message: string;
}
```

## Related

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/targets)

[ReferenceTargets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)

[![](https://shopify.dev/images/icons/32/apps.png)![](https://shopify.dev/images/icons/32/apps-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/components)

[ReferenceComponents](https://shopify.dev/docs/api/checkout-ui-extensions/components)

[![](https://shopify.dev/images/icons/32/gear.png)![](https://shopify.dev/images/icons/32/gear-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)

[ReferenceConfiguration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)

[![](https://shopify.dev/images/icons/32/tutorial.png)![](https://shopify.dev/images/icons/32/tutorial-dark.png)](https://shopify.dev/apps/checkout)

[LearnTutorials](https://shopify.dev/apps/checkout)