# Metafields

The API for interacting with metafields.

## StandardApi

The base API object provided to `purchase`, and `customer-account.order-status` extension targets.

### Docs_Standard_MetafieldsApi

### appMetafields

value: `StatefulRemoteSubscribable<AppMetafieldEntry[]>`

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.

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

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

### metafields

value: `StatefulRemoteSubscribable<Metafield[]>`

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)

### AppMetafieldEntry

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

### target

value: `AppMetafieldEntryTarget`

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

### metafield

value: `AppMetafield`

The metadata information.

### AppMetafieldEntryTarget

The metafield owner.

### type

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

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

### id

value: `string`

The numeric owner ID that is associated with the metafield.

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

### value

value: `string | number | boolean`

The value of a metafield.

### valueType

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

The metafield’s information type.

### type

value: `string`

The metafield's type name.

### 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: `"string" | "integer" | "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`


### type

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


### namespace

value: `string`


### key

value: `string`


### AppMetafieldEntry

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

### target

value: `AppMetafieldEntryTarget`

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

### metafield

value: `AppMetafield`

The metadata information.

### AppMetafieldEntryTarget

The metafield owner.

### type

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

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

### id

value: `string`

The numeric owner ID that is associated with the metafield.

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

### value

value: `string | number | boolean`

The value of a metafield.

### valueType

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

The metafield’s information type.

### type

value: `string`

The metafield's type name.

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

### namespace

value: `string`


### key

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

### namespace

value: `string`


### key

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

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.

### MetafieldRemoveChange

Removes a metafield.

### type

value: `"removeMetafield"`

The type of the `MetafieldRemoveChange` API.

### key

value: `string`

The name of the metafield to remove.

### namespace

value: `string`

The namespace of the metafield to remove.

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

### type

value: `"updateMetafield"`

The type of the `MetafieldUpdateChange` API.

### key

value: `string`

The name of the metafield to update.

### namespace

value: `string`

The namespace of the metafield to add.

### value

value: `string | number`

The new information to store in the metafield.

### valueType

value: `"string" | "integer" | "json_string"`

The metafield’s information type.

### MetafieldRemoveCartChange

Removes a cart metafield.

### type

value: `"removeCartMetafield"`

The type of the `MetafieldRemoveChange` API.

### key

value: `string`

The name of the metafield to remove.

### namespace

value: `string`

The namespace of the metafield to remove.

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

### value

value: `string`

The value of a metafield.

### type

value: `string`

The metafield's type name.

### MetafieldUpdateCartChange

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

### type

value: `"updateCartMetafield"`

The type of the `MetafieldUpdateChange` API.

### metafield

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


### MetafieldChangeResultSuccess

### type

value: `"success"`

The type of the `MetafieldChangeResultSuccess` API.

### MetafieldChangeResultError

### type

value: `"error"`

The type of the `MetafieldChangeResultError` API.

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

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

### type

value: `"removeMetafield"`

The type of the `MetafieldRemoveChange` API.

### key

value: `string`

The name of the metafield to remove.

### namespace

value: `string`

The namespace of the metafield to remove.

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

### type

value: `"updateMetafield"`

The type of the `MetafieldUpdateChange` API.

### key

value: `string`

The name of the metafield to update.

### namespace

value: `string`

The namespace of the metafield to add.

### value

value: `string | number`

The new information to store in the metafield.

### valueType

value: `"string" | "integer" | "json_string"`

The metafield’s information type.

### MetafieldRemoveCartChange

Removes a cart metafield.

### type

value: `"removeCartMetafield"`

The type of the `MetafieldRemoveChange` API.

### key

value: `string`

The name of the metafield to remove.

### namespace

value: `string`

The namespace of the metafield to remove.

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

### value

value: `string`

The value of a metafield.

### type

value: `string`

The metafield's type name.

### MetafieldUpdateCartChange

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

### type

value: `"updateCartMetafield"`

The type of the `MetafieldUpdateChange` API.

### metafield

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


### MetafieldChangeResultSuccess

### type

value: `"success"`

The type of the `MetafieldChangeResultSuccess` API.

### MetafieldChangeResultError

### type

value: `"error"`

The type of the `MetafieldChangeResultError` API.

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

## 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)