---
title: Metafields API
description: >-
  The Metafields API provides read-only access to metafields declared in your
  extension's configuration on the Order status page. Use this API to read
  custom data from products, variants, customers, orders, and other Shopify
  resources associated with the order.
api_version: 2026-04
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/metafields-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/metafields-api.md
---

# 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 read-only access to [metafields](https://shopify.dev/docs/apps/build/custom-data/metafields) declared in your extension's configuration on the [Order status page](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/order-status). Use this API to read custom data from products, variants, customers, orders, and other Shopify resources associated with the order. Learn about [using metafields in customer account UI extensions](https://shopify.dev/docs/apps/build/customer-accounts/metafields-in-customer-accounts).

Only metafields declared in your [`shopify.extension.toml`](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#configuration) are available. Undeclared metafields aren't returned.

### 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/2026-04/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-)

### Properties

The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#target-apis-define-what-your-extension-does) provides metafields requested by your extension. Access the following properties on `shopify` to read custom metadata attached to Shopify resources associated with the order.

* **appMetafields**

  **SubscribableSignalLike\<AppMetafieldEntry\[]>**

  **required**

  The [metafields](https://shopify.dev/docs/apps/build/custom-data/metafields) requested in the [`shopify.extension.toml`](https://shopify.dev/docs/apps/build/customer-accounts/metafields#create-the-metafield-definition) file. Metafields are custom data fields that store additional information on Shopify resources such as products, variants, customers, and the shop. 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/metafields#app-owned-metafields) for more information.

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

### SubscribableSignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends \`ReadonlySignalLike\` with deprecated fields that are still supported for backwards compatibility.

* current

  The current value of the signal. Equivalent to \`.value\`, accessing this property subscribes to changes when used in a reactive context.

  ```ts
  T
  ```

* destroy

  Cleans up the subscription and releases any resources held by this signal. After calling \`destroy()\`, the signal stops receiving updates from the main thread.

  ```ts
  () => Promise<void>
  ```

* subscribe

  Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.

  ```ts
  (fn: (value: T) => void) => () => void
  ```

* value

  The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.

  ```ts
  T
  ```

### AppMetafieldEntry

An entry that pairs a Shopify resource with one of its \[metafields]\(/docs/apps/build/custom-data/metafields). Each entry contains a \`target\` identifying which resource the metafield belongs to and a \`metafield\` object with the actual data.

* metafield

  The metafield data, including the namespace, key, value, and content type. Use the \`namespace\` and \`key\` together to uniquely identify the metafield within its resource.

  ```ts
  AppMetafield
  ```

* target

  The Shopify resource that this metafield is attached to, including the resource type (such as \`'product'\` or \`'customer'\`) and its globally-unique ID. {% 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
  AppMetafieldEntryTarget
  ```

### AppMetafield

Represents a custom \[metafield]\(/docs/apps/build/custom-data/metafields) attached to a resource such as a product, variant, customer, or shop.

* key

  The identifier for the metafield within its namespace, such as \`'ingredients'\` or \`'shipping\_weight'\`.

  ```ts
  string
  ```

* namespace

  The namespace that the metafield belongs to. Namespaces group related metafields and prevent naming collisions between different apps. App owned metafield namespaces are returned using the \`$app\` format. See \[app owned metafields]\(/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.

  ```ts
  string
  ```

* type

  The metafield's \[type name]\(/docs/apps/build/custom-data/metafields/list-of-data-types), such as \`'single\_line\_text\_field'\` or \`'json'\`. This is the full type identifier, whereas \`valueType\` is a simplified category.

  ```ts
  string
  ```

* value

  The value of a metafield, stored as a string regardless of the underlying type. For JSON metafields, parse the string to access structured data.

  ```ts
  string
  ```

* valueType

  The metafield's information type. - \`'boolean'\`: A true or false value. - \`'float'\`: A decimal number value. - \`'integer'\`: A whole number value. - \`'json\_string'\`: A JSON-encoded string value. - \`'string'\`: A plain text value.

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

### AppMetafieldEntryTarget

The Shopify resource that a metafield is attached to. Each entry identifies a specific resource by its type and globally-unique ID, so you can trace where the data comes from.

* id

  The globally-unique identifier of the Shopify resource, in \[GID]\(/docs/api/usage/gids) format. Use this value to match the metafield to a specific resource in your extension or when querying the \[Storefront API]\(/docs/api/storefront).

  ```ts
  string
  ```

* type

  The kind of Shopify resource this metafield belongs to: - \`'customer'\`: The customer who placed the order. - \`'product'\`: A product in the merchant's catalog. - \`'shop'\`: The merchant's shop. - \`'shopUser'\`: A staff member or collaborator account on the shop. - \`'variant'\`: A specific variant of a product. - \`'company'\`: A \[B2B]\(/docs/apps/build/b2b) company associated with the order. - \`'companyLocation'\`: A location belonging to a \[B2B]\(/docs/apps/build/b2b) company. - \`'cart'\`: The cart associated with the checkout. {% include /apps/checkout/privacy-icon.md %} Requires level 1 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'
      | 'shopUser'
      | 'variant'
      | 'company'
      | 'companyLocation'
      | 'cart'
  ```

Examples

### Examples

* ####

  ##### Description

  Read product metafields to display additional information such as care instructions. This example filters \`shopify.appMetafields\` by \`target.type === 'product'\` and looks up a specific namespace and key to render the metafield value.

  ##### jsx

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default async () => {
    render(<Extension />, document.body);
  };

  function Extension() {
    const metafields =
      shopify.appMetafields.value;

    const careInstructions = metafields.find(
      (entry) =>
        entry.target.type === 'product' &&
        entry.metafield.namespace === 'custom' &&
        entry.metafield.key === 'care_instructions',
    );

    if (!careInstructions) {
      return null;
    }

    return (
      <s-box>
        <s-text type="strong">
          Care instructions
        </s-text>
        <s-text>
          {careInstructions.metafield.value}
        </s-text>
      </s-box>
    );
  }
  ```

* ####

  ##### Description

  Separate metafields by the type of Shopify resource they belong to. This example groups entries from \`shopify.appMetafields\` by \`target.type\` into product, variant, and shop categories, then displays each group.

  ##### jsx

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default async () => {
    render(<Extension />, document.body);
  };

  function Extension() {
    const metafields =
      shopify.appMetafields.value;

    const productMetafields = metafields.filter(
      (entry) => entry.target.type === 'product',
    );
    const variantMetafields = metafields.filter(
      (entry) => entry.target.type === 'variant',
    );
    const shopMetafields = metafields.filter(
      (entry) => entry.target.type === 'shop',
    );

    return (
      <s-box>
        <s-text type="strong">
          Metafields by resource
        </s-text>
        <s-text>
          Products: {productMetafields.length}
        </s-text>
        <s-text>
          Variants: {variantMetafields.length}
        </s-text>
        <s-text>
          Shop: {shopMetafields.length}
        </s-text>
      </s-box>
    );
  }
  ```

* ####

  ##### Description

  Display a customer's loyalty tier from a customer metafield. This example finds the metafield entry where \`target.type === 'customer'\` and renders the loyalty tier value in a banner.

  ##### jsx

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default async () => {
    render(<Extension />, document.body);
  };

  function Extension() {
    const metafields =
      shopify.appMetafields.value;

    const loyaltyEntry = metafields.find(
      (entry) =>
        entry.target.type === 'customer' &&
        entry.metafield.namespace === 'loyalty' &&
        entry.metafield.key === 'tier',
    );

    if (!loyaltyEntry) {
      return null;
    }

    const tier = loyaltyEntry.metafield.value;

    return (
      <s-banner>
        <s-text>
          Your loyalty tier:{' '}
          <s-text type="strong">{tier}</s-text>
        </s-text>
      </s-banner>
    );
  }
  ```

***

## Best practices

* **Filter by resource type**: The `appMetafields` array can contain metafields from multiple resource types (products, variants, customers, shop, and more). Filter entries by `target.type` to find the metafields you need.

***