---
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: 2027-01
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/target-apis/order-apis/metafields-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/target-apis/order-apis/metafields-api.md
api_name: customer-account-ui-extensions
---

# Metafields API

**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.:**

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/2027-01-rc/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/2027-01-rc#configuration) are available. Undeclared metafields aren't returned.

Each declaration takes a `namespace`, a `key`, and an `owner_type` that names the resource the metafield is attached to. Refer to the [supported owner types](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc#configuration).

## shopify.extension.toml

```toml
[[extensions.metafields]]
namespace = "$app"
key = "care-instructions"
owner_type = "PRODUCT"
```

**Caution:**

Starting in API version 2027-01, `owner_type` is required. Extensions on earlier API versions can omit it.

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

### Properties

The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc#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.

* **app​Metafields**

  **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. Use \`appMetafields\` on the Order API to access these entries.

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

  ```ts
  AppMetafieldEntryTarget
  ```

### AppMetafield

A \[metafield]\(/docs/apps/build/custom-data/metafields) attached to a Shopify resource, such as a product, variant, customer, or the shop. Metafields let merchants and apps store custom data beyond what Shopify provides by default.

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

  ```ts
  string
  ```

* type

  The metafield's \[content type]\(/docs/apps/build/custom-data/metafields/list-of-data-types), which provides more specific type information than \`valueType\`. For example, \`'single\_line\_text\_field'\`, \`'number\_integer'\`, or \`'json'\`.

  ```ts
  string
  ```

* value

  The data stored in the metafield. The format depends on the \`valueType\`: a string for \`'string'\`, a number for \`'integer'\` or \`'float'\`, a boolean for \`'boolean'\`, or a serialized JSON object for \`'json\_string'\`.

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

* valueType

  The data type of the metafield value. Determines how to interpret the \`value\` field: - \`'boolean'\`: A \`true\` or \`false\` value. - \`'float'\`: A decimal number. - \`'integer'\`: A whole number. - \`'json\_string'\`: A serialized JSON object or array. - \`'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 your extension can determine where the metafield data originates.

* 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 GraphQL API.

  ```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. - \`'variant'\`: A specific variant of a product. - \`'company'\`: A B2B company associated with the order. - \`'companyLocation'\`: A location belonging to a B2B company. - \`'cart'\`: The cart associated with the order. {% 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'
      | 'variant'
      | 'company'
      | 'companyLocation'
      | 'cart'
      | 'order'
  ```

### Examples

* #### Display product care instructions

  ##### 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>
    );
  }
  ```

* #### Filter metafields by resource type

  ##### 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>
    );
  }
  ```

* #### Show a customer loyalty tier

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

***