# Metafields

The API for interacting with metafields.

```jsx
import {
  reactExtension,
  Text,
  useAppMetafields,
  useCartLineTarget,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.cart-line-item.render-after',
  () => <Extension />,
);

function Extension() {
  const {
    merchandise: {id: productVariantId},
  } = useCartLineTarget();

  const [energyRating] = useAppMetafields({
    namespace: '$app',
    key: 'energy-rating',
    type: 'product',
  }).filter(
    (entry) =>
      entry.target.id === productVariantId,
  );

  return (
    energyRating && (
      <Text>
        Energy rating:{' '}
        {energyRating.metafield.value}
      </Text>
    )
  );
}

```

```js
import {
  extension,
  Text,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.cart-line-item.render-after',
  (root, api) => {
    const productVariantId =
      api.target.current.merchandise.id;

    const filterMetafields = (entries) => {
      const [energyRating] = entries.filter(
        (entry) =>
          entry.metafield.namespace === '$app' &&
          entry.metafield.key ===
            'energy-rating' &&
          entry.target.type === 'product' &&
          entry.target.id === productVariantId,
      );
      return energyRating;
    };

    const render = (energyRating) => {
      if (energyRating) {
        root.replaceChildren(
          root.createComponent(
            Text,
            {},
            `Energy rating: ${energyRating.metafield.value}`,
          ),
        );
      }
    };

    render(
      filterMetafields(api.appMetafields.current),
    );
    api.appMetafields.subscribe((entries) => {
      render(filterMetafields(entries));
    });
  },
);

```

```toml
# other configs omitted

[[extensions.metafields]]
# tip: you can use $app:some-namespace to further segment your data
namespace = "$app"
key = "energy-rating"

```

## StandardApi

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

### Docs_Standard_MetafieldsApi

### appMetafields

value: `StatefulRemoteSubscribable<AppMetafieldEntry[]>`

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

  /** The metadata information. */
  metafield: AppMetafield;
}
  - AppMetafield: export interface AppMetafield {
  /** The key name of a metafield. */
  key: string;

  /**
   * The namespace for a metafield.
   *
   * App owned metafield namespaces are returned using the `$app` format. See [app owned metafields](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.
   */
  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;
}
  - Metafield: 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';
}
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.

App owned metafields are supported and are returned using the `$app` format. The fully qualified reserved namespace format such as `app--{your-app-id}[--{optional-namespace}]` is not supported. See [app owned metafields](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.

{% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

### metafields

value: `StatefulRemoteSubscribable<Metafield[]>`

  - Metafield: 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';
}
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

value: `AppMetafield`

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

  /**
   * The namespace for a metafield.
   *
   * App owned metafield namespaces are returned using the `$app` format. See [app owned metafields](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.
   */
  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;
}
  - Metafield: 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';
}
The metadata information.

### target

value: `AppMetafieldEntryTarget`

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

  /** The metadata information. */
  metafield: AppMetafield;
}
  - AppMetafield: export interface AppMetafield {
  /** The key name of a metafield. */
  key: string;

  /**
   * The namespace for a metafield.
   *
   * App owned metafield namespaces are returned using the `$app` format. See [app owned metafields](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.
   */
  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: export interface AppMetafieldEntryTarget {
  /**
   * The type of the metafield owner.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/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: 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';
}
The target that is associated to the metadata.

{% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.

### AppMetafield

Represents a custom metadata attached to a resource.

### key

value: `string`

The key name of a metafield.

### namespace

value: `string`

The namespace for a metafield.

App owned metafield namespaces are returned using the `$app` format. See [app owned metafields](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.

### type

value: `string`

The metafield's type name.

### value

value: `string | number | boolean`

The value of a metafield.

### valueType

value: `'boolean' | 'float' | 'integer' | 'json_string' | 'string'`

The metafield’s information type.

### AppMetafieldEntryTarget

The metafield owner.

### id

value: `string`

The numeric owner ID that is associated with the metafield.

### type

value: `| 'customer'
    | 'product'
    | 'shop'
    | 'shopUser'
    | 'variant'
    | 'company'
    | 'companyLocation'
    | 'cart'`

The type of the metafield owner.

{% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.

### Metafield

Metadata associated with the checkout.

### key

value: `string`

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

### namespace

value: `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).

### value

value: `string | number`

The information to be stored as metadata.

### valueType

value: `'integer' | 'string' | 'json_string'`

The metafield’s information type.

## Related

- [Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)
- [Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)
- [Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)
- [Tutorials](/apps/checkout)

## useAppMetafields

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

### UseAppMetafieldsGeneratedType

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

#### Returns: AppMetafieldEntry[]

#### Params:

- filters: AppMetafieldFilters
export function useAppMetafields<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(filters: AppMetafieldFilters = {}): AppMetafieldEntry[] {
  const appMetafields = useSubscription(useApi<Target>().appMetafields);

  return useMemo(() => {
    if (filters.key && !filters.namespace) {
      throw new CheckoutUIExtensionError(
        'You must pass in a namespace with a key',
      );
    }

    const filterKeys = Object.keys(filters) as AppMetafieldFilterKeys[];

    if (filterKeys.length) {
      return appMetafields.filter((app) => {
        return filterKeys.every((key) => {
          if (key === 'id' || key === 'type') {
            return app.target[key] === filters[key];
          }

          return app.metafield[key] === filters[key];
        });
      });
    }

    return appMetafields;
  }, [filters, appMetafields]);
}


### AppMetafieldFilters

### id

value: `string`


### key

value: `string`


### namespace

value: `string`

To filter for app owned metafields, use the `$app` format. The fully qualified reserved namespace format such as `app--{your-app-id}[--{optional-namespace}]` is not supported.

See [app owned metafields](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.

### type

value: `"customer" | "product" | "shop" | "shopUser" | "variant" | "company" | "companyLocation" | "cart"`


### AppMetafieldEntry

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

### metafield

value: `AppMetafield`

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

  /**
   * The namespace for a metafield.
   *
   * App owned metafield namespaces are returned using the `$app` format. See [app owned metafields](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.
   */
  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;
}
The metadata information.

### target

value: `AppMetafieldEntryTarget`

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

  /** The metadata information. */
  metafield: AppMetafield;
}
  - AppMetafield: export interface AppMetafield {
  /** The key name of a metafield. */
  key: string;

  /**
   * The namespace for a metafield.
   *
   * App owned metafield namespaces are returned using the `$app` format. See [app owned metafields](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.
   */
  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: export interface AppMetafieldEntryTarget {
  /**
   * The type of the metafield owner.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/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;
}
The target that is associated to the metadata.

{% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.

### AppMetafield

Represents a custom metadata attached to a resource.

### key

value: `string`

The key name of a metafield.

### namespace

value: `string`

The namespace for a metafield.

App owned metafield namespaces are returned using the `$app` format. See [app owned metafields](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.

### type

value: `string`

The metafield's type name.

### value

value: `string | number | boolean`

The value of a metafield.

### valueType

value: `'boolean' | 'float' | 'integer' | 'json_string' | 'string'`

The metafield’s information type.

### AppMetafieldEntryTarget

The metafield owner.

### id

value: `string`

The numeric owner ID that is associated with the metafield.

### type

value: `| 'customer'
    | 'product'
    | 'shop'
    | 'shopUser'
    | 'variant'
    | 'company'
    | 'companyLocation'
    | 'cart'`

The type of the metafield owner.

{% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.

## Related

- [Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)
- [Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)
- [Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)
- [Tutorials](/apps/checkout)

## useMetafield

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

### UseMetafieldGeneratedType

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

#### Returns: Metafield | undefined

#### Params:

- filters: MetafieldFilter
export function useMetafield(filters: MetafieldFilter): Metafield | undefined {
  const {namespace, key} = filters;

  if (!namespace || !key) {
    throw new CheckoutUIExtensionError(
      'You must pass in both a namespace and key',
    );
  }

  const metafields = useMetafields({namespace, key});

  return metafields.length ? metafields[0] : undefined;
}


### MetafieldFilter

### key

value: `string`


### namespace

value: `string`


### Metafield

Metadata associated with the checkout.

### key

value: `string`

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

### namespace

value: `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).

### value

value: `string | number`

The information to be stored as metadata.

### valueType

value: `'integer' | 'string' | 'json_string'`

The metafield’s information type.

## Related

- [Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)
- [Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)
- [Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)
- [Tutorials](/apps/checkout)

## useMetafields

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

### UseMetafieldsGeneratedType

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

#### Returns: Metafield[]

#### Params:

- filters: MetafieldsFilters
export function useMetafields<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(filters?: MetafieldsFilters): Metafield[] {
  const metaFields = useSubscription(useApi<Target>().metafields);

  return useMemo(() => {
    if (filters) {
      const {namespace, key} = filters;

      if (!namespace) {
        throw new CheckoutUIExtensionError(
          'You must pass in a namespace with a key',
        );
      }

      const filteredResults = metaFields.filter(
        (metafield) =>
          metafield.namespace === namespace && (!key || metafield.key === key),
      );

      return filteredResults;
    }

    return metaFields;
  }, [filters, metaFields]);
}


### MetafieldsFilters

### key

value: `string`


### namespace

value: `string`


### Metafield

Metadata associated with the checkout.

### key

value: `string`

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

### namespace

value: `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).

### value

value: `string | number`

The information to be stored as metadata.

### valueType

value: `'integer' | 'string' | 'json_string'`

The metafield’s information type.

## Related

- [Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)
- [Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)
- [Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)
- [Tutorials](/apps/checkout)

## CheckoutApi

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

### Docs_Checkout_MetafieldsApi

### applyMetafieldChange

value: `(change: MetafieldChange) => Promise<MetafieldChangeResult>`

  - MetafieldChange: MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange
  - Metafield: 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';
}
  - MetafieldChangeResult: MetafieldChangeResultSuccess | MetafieldChangeResultError
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.

### MetafieldRemoveChange

Removes a metafield.

### key

value: `string`

The name of the metafield to remove.

### namespace

value: `string`

The namespace of the metafield to remove.

### type

value: `"removeMetafield"`

  - Metafield: 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';
}
The type of the `MetafieldRemoveChange` API.

### Metafield

Metadata associated with the checkout.

### key

value: `string`

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

### namespace

value: `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).

### value

value: `string | number`

The information to be stored as metadata.

### valueType

value: `'integer' | 'string' | 'json_string'`

The metafield’s information type.

### MetafieldUpdateChange

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

### key

value: `string`

The name of the metafield to update.

### namespace

value: `string`

The namespace of the metafield to add.

### type

value: `"updateMetafield"`

  - Metafield: 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';
}
The type of the `MetafieldUpdateChange` API.

### value

value: `string | number`

The new information to store in the metafield.

### valueType

value: `'integer' | 'string' | 'json_string'`

The metafield’s information type.

### MetafieldRemoveCartChange

Removes a cart metafield.

### key

value: `string`

The name of the metafield to remove.

### namespace

value: `string`

The namespace of the metafield to remove.

### type

value: `"removeCartMetafield"`

  - Metafield: 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';
}
  - CartMetafield: export interface CartMetafield {
  /** The key name of a metafield. */
  key: string;

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

  /** The value of a metafield. */
  value: string;

  /** The metafield's type name. */
  type: string;
}
The type of the `MetafieldRemoveChange` API.

### CartMetafield

Represents a custom metadata attached to a resource.

### key

value: `string`

The key name of a metafield.

### namespace

value: `string`

The namespace for a metafield.

### type

value: `string`

The metafield's type name.

### value

value: `string`

The value of a metafield.

### MetafieldUpdateCartChange

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

### metafield

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


### type

value: `"updateCartMetafield"`

  - Metafield: 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';
}
  - CartMetafield: export interface CartMetafield {
  /** The key name of a metafield. */
  key: string;

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

  /** The value of a metafield. */
  value: string;

  /** The metafield's type name. */
  type: string;
}
The type of the `MetafieldUpdateChange` API.

### MetafieldChangeResultSuccess

### type

value: `"success"`

The type of the `MetafieldChangeResultSuccess` API.

### MetafieldChangeResultError

### message

value: `string`

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.

### type

value: `"error"`

The type of the `MetafieldChangeResultError` API.

## Related

- [Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)
- [Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)
- [Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)
- [Tutorials](/apps/checkout)

## useApplyMetafieldsChange

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

### UseApplyMetafieldsChangeGeneratedType

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

#### Returns: (change: MetafieldChange) => Promise<MetafieldChangeResult>
export function useApplyMetafieldsChange<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(): (change: MetafieldChange) => Promise<MetafieldChangeResult> {
  const api = useApi<Target>();

  if ('applyMetafieldChange' in api) {
    return api.applyMetafieldChange;
  }

  throw new ExtensionHasNoMethodError(
    'applyMetafieldChange',
    api.extension.target,
  );
}


### MetafieldRemoveChange

Removes a metafield.

### key

value: `string`

The name of the metafield to remove.

### namespace

value: `string`

The namespace of the metafield to remove.

### type

value: `"removeMetafield"`

  - Metafield: 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';
}
The type of the `MetafieldRemoveChange` API.

### Metafield

Metadata associated with the checkout.

### key

value: `string`

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

### namespace

value: `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).

### value

value: `string | number`

The information to be stored as metadata.

### valueType

value: `'integer' | 'string' | 'json_string'`

The metafield’s information type.

### MetafieldUpdateChange

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

### key

value: `string`

The name of the metafield to update.

### namespace

value: `string`

The namespace of the metafield to add.

### type

value: `"updateMetafield"`

  - Metafield: 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';
}
The type of the `MetafieldUpdateChange` API.

### value

value: `string | number`

The new information to store in the metafield.

### valueType

value: `'integer' | 'string' | 'json_string'`

The metafield’s information type.

### MetafieldRemoveCartChange

Removes a cart metafield.

### key

value: `string`

The name of the metafield to remove.

### namespace

value: `string`

The namespace of the metafield to remove.

### type

value: `"removeCartMetafield"`

  - Metafield: 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';
}
  - CartMetafield: export interface CartMetafield {
  /** The key name of a metafield. */
  key: string;

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

  /** The value of a metafield. */
  value: string;

  /** The metafield's type name. */
  type: string;
}
The type of the `MetafieldRemoveChange` API.

### CartMetafield

Represents a custom metadata attached to a resource.

### key

value: `string`

The key name of a metafield.

### namespace

value: `string`

The namespace for a metafield.

### type

value: `string`

The metafield's type name.

### value

value: `string`

The value of a metafield.

### MetafieldUpdateCartChange

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

### metafield

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


### type

value: `"updateCartMetafield"`

  - Metafield: 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';
}
  - CartMetafield: export interface CartMetafield {
  /** The key name of a metafield. */
  key: string;

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

  /** The value of a metafield. */
  value: string;

  /** The metafield's type name. */
  type: string;
}
The type of the `MetafieldUpdateChange` API.

### MetafieldChangeResultSuccess

### type

value: `"success"`

The type of the `MetafieldChangeResultSuccess` API.

### MetafieldChangeResultError

### message

value: `string`

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.

### type

value: `"error"`

The type of the `MetafieldChangeResultError` API.

## Related

- [Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)
- [Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)
- [Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)
- [Tutorials](/apps/checkout)