Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Metafields API

Requires Level 1 access to 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.

Anchor to Use casesUse 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

Anchor to PropertiesProperties

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

Anchor to appMetafields appMetafields StatefulRemoteSubscribable<[]> required: The metafields requested in the shopify.extension.toml file. These metafields are updated when there’s a change in the merchandise items being purchased by the customer.

Requires access to protected customer data.
Anchor to metafields metafields StatefulRemoteSubscribable<[]> 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.

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.
```
AppMetafield
```
target
The resource that owns the metafield.
```
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.
```
string
```
namespace
A container that groups related metafields. Must be between 2 and 255 characters in length.
```
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`.
```
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.
```
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.
```
'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.
```
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`.
```
| '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).
```
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).
```
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.
```
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.
```
'integer' | 'string' | 'json_string'
```

Examples

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 (

<Text emphasis="bold">Custom data</Text>

{appMetafields.map((entry) => (

{entry.metafield.namespace}.{entry.metafield.key}:{' '}

{String(entry.metafield.value)}

</Text>

))}

</BlockStack>

);

}

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

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

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

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

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

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

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);
  },
);

Anchor to Best practicesBest practices

Configure app metafields in your TOML file: App metafields must be declared in your shopify.extension.toml 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.

Anchor to LimitationsLimitations

App metafields must be declared in your shopify.extension.toml 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.

Was this page helpful?