---
title: Metafields API
description: >-
  The Metafields API provides the app metafields and order metafields associated
  with the order. Use it to read custom data that your app or other apps have
  stored on order resources on the Order status page.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/metafields-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/metafields-api.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# Metafields API

**Requires Level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data) when accessing metafields attached to \`customer\`, \`company\`, or \`companyLocation\` resources.:**

The Metafields API provides the app metafields and order metafields associated with the order. Use it to read custom data that your app or other apps have stored on order resources on the Order status page. Learn about [using metafields in customer account UI extensions](https://shopify.dev/docs/apps/build/customer-accounts/metafields-in-customer-accounts).

### Use cases

* **Display custom product data**: Read metafields on products or variants to display additional information, such as care instructions, material details, or warranty terms.
* **Show customer-specific data**: Access metafields on the customer resource to display loyalty points, membership tiers, or other customer-specific metadata.
* **Read order metadata**: Access metafields on the order to display custom data set by your app or other extensions, such as delivery promises or fulfillment notes.

### Support Targets (10)

### Supported targets

* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)

### Properties

The Metafields API object provides app metafields and order metafields. Access the following properties on the API object to read metafield data.

* **appMetafields**

  **StatefulRemoteSubscribable\<AppMetafieldEntry\[]>**

  **required**

  The metafields requested in the [`shopify.extension.toml`](https://shopify.dev/docs/apps/build/customer-accounts/metafields#create-the-metafield-definition) 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).

* **metafields**

  **StatefulRemoteSubscribable\<Metafield\[]>**

  **required**

  The metafields that apply to the current order. These metafields are shared by all extensions running on the **Order status** page and persist for the duration of the buyer's session.

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

### AppMetafieldEntry

A metafield associated with a resource on the order. Each entry contains both the metafield data and a reference to the resource that owns it.

* metafield

  The metafield data, including its key, namespace, value, and type.

  ```ts
  AppMetafield
  ```

* target

  The resource that owns the metafield.

  ```ts
  AppMetafieldEntryTarget
  ```

### AppMetafield

Represents a custom metadata field attached to a resource, requested through the \[\`shopify.extension.toml\`]\(/docs/apps/build/customer-accounts/metafields#create-the-metafield-definition) file.

* key

  The unique identifier for the metafield within its namespace.

  ```ts
  string
  ```

* namespace

  A container that groups related metafields. Must be between 2 and 255 characters in length.

  ```ts
  string
  ```

* type

  The metafield's content type as defined in the \[metafield definition]\(/docs/apps/build/custom-data/metafields), such as \`single\_line\_text\_field\` or \`number\_integer\`.

  ```ts
  string
  ```

* value

  The metafield's value. The data type depends on the \`valueType\`: booleans, numbers, and strings are returned in their respective types, while JSON strings are returned as strings.

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

* valueType

  The metafield’s value type, which determines how the \`value\` is interpreted: - \`'boolean'\`: A true or false value. - \`'float'\`: A decimal number. - \`'integer'\`: A whole number. - \`'json\_string'\`: A JSON-encoded string. - \`'string'\`: A plain text string.

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

### AppMetafieldEntryTarget

The resource that owns the metafield.

* id

  The globally-unique identifier of the resource that owns the metafield.

  ```ts
  string
  ```

* type

  The type of resource that owns the metafield: - \`'customer'\`: A customer resource. - \`'product'\`: A product resource. - \`'shop'\`: The shop resource. - \`'variant'\`: A product variant resource. - \`'company'\`: A B2B company resource. - \`'companyLocation'\`: A B2B company location resource. - \`'cart'\`: The cart resource. {% 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'
      | 'variant'
      | 'company'
      | 'companyLocation'
      | 'cart'
  ```

### Metafield

Represents a custom metadata field attached to a resource. Metafields let you store additional structured data on Shopify resources like orders and products.

* key

  The unique identifier for the metafield within its namespace. Must be between 3 and 30 characters in length (inclusive).

  ```ts
  string
  ```

* namespace

  A container for a group of metafields. Namespaces distinguish your app's metafields from those created by other apps. Must be between 2 and 20 characters in length (inclusive).

  ```ts
  string
  ```

* value

  The metafield's value. The data type depends on the \`valueType\`: integers are returned as numbers, while strings and JSON strings are returned as strings.

  ```ts
  string | number
  ```

* valueType

  The metafield’s value type, which determines how the \`value\` is interpreted: - \`'integer'\`: A whole number. - \`'string'\`: A plain text string. - \`'json\_string'\`: A JSON-encoded string.

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

Examples

### Examples

* ####

  ##### Description

  Read the app metafields configured in the extension TOML and display each entry. This example uses the \`useAppMetafields\` hook and render each metafield's key, namespace, and value.

  ##### React

  ```tsx
  import {
    reactExtension,
    useAppMetafields,
  } from '@shopify/ui-extensions-react/customer-account';
  import {
    BlockStack,
    Text,
  } from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const appMetafields = useAppMetafields();

    if (appMetafields.length === 0) {
      return null;
    }

    return (
      <BlockStack>
        <Text emphasis="bold">Custom data</Text>
        {appMetafields.map((entry) => (
          <Text key={`${entry.target.type}-${entry.metafield.key}`}>
            {entry.metafield.namespace}.{entry.metafield.key}:{' '}
            {String(entry.metafield.value)}
          </Text>
        ))}
      </BlockStack>
    );
  }
  ```

  ##### TS

  ```ts
  import {
    extension,
    BlockStack,
    Text,
  } from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      const appMetafields = api.appMetafields.current;

      if (appMetafields.length === 0) return;

      const stack = root.createComponent(BlockStack, {});
      stack.appendChild(
        root.createComponent(Text, {emphasis: 'bold'}, 'Custom data'),
      );

      for (const entry of appMetafields) {
        stack.appendChild(
          root.createComponent(
            Text,
            {},
            `${entry.metafield.namespace}.${entry.metafield.key}: ${String(entry.metafield.value)}`,
          ),
        );
      }
      root.appendChild(stack);
    },
  );
  ```

* ####

  ##### Description

  Filter app metafields to show only product-type entries. This example uses \`useAppMetafields\` and filters the results by the \`target.type\` property.

  ##### React

  ```tsx
  import {
    reactExtension,
    useAppMetafields,
  } from '@shopify/ui-extensions-react/customer-account';
  import {
    BlockStack,
    Text,
  } from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const productMetafields = useAppMetafields({
      type: 'product',
    });

    if (productMetafields.length === 0) {
      return null;
    }

    return (
      <BlockStack>
        <Text emphasis="bold">Product details</Text>
        {productMetafields.map((entry) => (
          <Text key={entry.metafield.key}>
            {entry.metafield.key}: {String(entry.metafield.value)}
          </Text>
        ))}
      </BlockStack>
    );
  }
  ```

  ##### TS

  ```ts
  import {
    extension,
    BlockStack,
    Text,
  } from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      const allMetafields = api.appMetafields.current;
      const productMetafields = allMetafields.filter(
        (entry) => entry.target.type === 'product',
      );

      if (productMetafields.length === 0) return;

      const stack = root.createComponent(BlockStack, {});
      stack.appendChild(
        root.createComponent(Text, {emphasis: 'bold'}, 'Product details'),
      );

      for (const entry of productMetafields) {
        stack.appendChild(
          root.createComponent(
            Text,
            {},
            `${entry.metafield.key}: ${String(entry.metafield.value)}`,
          ),
        );
      }
      root.appendChild(stack);
    },
  );
  ```

* ####

  ##### Description

  Read the order metafields and display them in a list. This example uses the \`useMetafield\` hook to look up a specific metafield by namespace and key.

  ##### React

  ```tsx
  import {
    reactExtension,
    useMetafield,
  } from '@shopify/ui-extensions-react/customer-account';
  import {
    Banner,
    Text,
  } from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const loyaltyPoints = useMetafield({
      namespace: 'loyalty',
      key: 'points_earned',
    });

    if (!loyaltyPoints) {
      return null;
    }

    return (
      <Banner status="success">
        <Text>
          You earned {loyaltyPoints.value} loyalty points on
          this order!
        </Text>
      </Banner>
    );
  }
  ```

  ##### TS

  ```ts
  import {
    extension,
    Banner,
    Text,
  } from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      const metafields = api.metafields.current;
      const loyaltyPoints = metafields.find(
        (m) => m.namespace === 'loyalty' && m.key === 'points_earned',
      );

      if (!loyaltyPoints) return;

      const banner = root.createComponent(Banner, {status: 'success'});
      banner.appendChild(
        root.createComponent(
          Text,
          {},
          `You earned ${loyaltyPoints.value} loyalty points on this order!`,
        ),
      );
      root.appendChild(banner);
    },
  );
  ```

***

## Best practices

* **Configure app metafields in your TOML file**: App metafields must be declared in your [`shopify.extension.toml`](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#configuration) before they're available through the `appMetafields` property.
* **Use `useMetafield` for order metafield lookups**: When you need a specific order metafield, use `useMetafield` with the namespace and key instead of filtering the full `metafields` list.

***

## Limitations

* App metafields must be declared in your [`shopify.extension.toml`](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#configuration) file before they're available through `appMetafields`. Undeclared app metafields aren't returned.
* Order metafields are shared across all extensions on the Order status page and don't require TOML configuration.
* Metafield values are returned as strings regardless of their content type. If a metafield contains JSON or other structured data, you need to parse it in your extension.

***