---
title: useApplyMetafieldsChange
description: Returns a function to mutate the `metafields` property of the checkout.
api_version: 2023-07
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2023-07/react-hooks/metafields/useapplymetafieldschange
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2023-07/react-hooks/metafields/useapplymetafieldschange.md
---

# use​Apply​Metafields​Changehook

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

## use​Apply​Metafields​Change()

### Returns

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

### MetafieldChange

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

### MetafieldRemoveChange

Removes a metafield.

* type

  The type of the \`MetafieldRemoveChange\` API.

  ```ts
  "removeMetafield"
  ```

* key

  The name of the metafield to remove.

  ```ts
  string
  ```

* namespace

  The namespace of the metafield to remove.

  ```ts
  string
  ```

```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.

* type

  The type of the \`MetafieldUpdateChange\` API.

  ```ts
  "updateMetafield"
  ```

* key

  The name of the metafield to update.

  ```ts
  string
  ```

* namespace

  The namespace of the metafield to add.

  ```ts
  string
  ```

* value

  The new information to store in the metafield.

  ```ts
  string | number
  ```

* valueType

  The metafield’s information type.

  ```ts
  "string" | "integer" | "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.

* type

  The type of the \`MetafieldRemoveChange\` API.

  ```ts
  "removeCartMetafield"
  ```

* key

  The name of the metafield to remove.

  ```ts
  string
  ```

* namespace

  The namespace of the metafield to remove.

  ```ts
  string
  ```

```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.

* type

  The type of the \`MetafieldUpdateChange\` API.

  ```ts
  "updateCartMetafield"
  ```

* metafield

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

```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

* type

  The type of the \`MetafieldChangeResultError\` API.

  ```ts
  "error"
  ```

* 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
  ```

```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

[APIs - StandardApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi)

[APIs - CheckoutApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/checkoutapi)

[APIs - OrderStatusApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/orderstatusapi)

[APIs - CartLineItemApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cartlineitemapi)

[APIs - PickupPointListApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuppointlistapi)

[APIs - PickupLocationListApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuplocationlistapi)

[APIs - ShippingOptionItemApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/shippingoptionitemapi)

[APIs - ExtensionTargets](https://shopify.dev/docs/api/checkout-ui-extensions/apis/extensiontargets)