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 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. Learn about using metafields in customer account UI extensions.

Only metafields declared in your shopify.extension.toml are available. Undeclared metafields aren't returned.

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 shopify global object provides metafields requested by your extension. Access the following properties on shopify to read custom metadata attached to Shopify resources associated with the order.

Anchor to appMetafields appMetafields <[]> required: The metafields requested in the shopify.extension.toml 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.

Requires level 1 access to protected customer data when accessing metafields attached to customer, company, or companyLocation resources.
Anchor to metafields metafields <[]> required: The metafields associated with the order. These metafields are shared across all extensions and persist throughout the checkout session.

Deprecated
Use appMetafields instead, which provides richer data including the resource type and metafield content type.

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.
```
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.
```
() => 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.
```
(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.
```
T
```

AppMetafieldEntry

An entry that pairs a Shopify resource with one of its [metafields](https://shopify.dev/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.
```
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](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.
```
AppMetafieldEntryTarget
```

AppMetafield

Represents a custom [metafield](https://shopify.dev/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'`.
```
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](https://shopify.dev/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.
```
string
```
type
The metafield's [type name](https://shopify.dev/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.
```
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.
```
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.
```
'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](https://shopify.dev/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](https://shopify.dev/docs/api/storefront).
```
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](https://shopify.dev/docs/apps/build/b2b) company associated with the order. - `'companyLocation'`: A location belonging to a [B2B](https://shopify.dev/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](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.
```
| 'customer'
    | 'product'
    | 'shop'
    | 'shopUser'
    | 'variant'
    | 'company'
    | 'companyLocation'
    | 'cart'
```

Metafield

Metadata associated with the checkout. See the [metafields documentation](https://shopify.dev/docs/apps/build/custom-data/metafields) for more information on how metafields work.

key
The name of the metafield.
```
string
```
namespace
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.
```
string
```
value
The information to be stored as metadata.
```
string | number
```
valueType
The metafield's information type. - `'integer'`: A whole number value. - `'string'`: A plain text value. - `'json_string'`: A JSON-encoded string value.
```
'integer' | 'string' | 'json_string'
```

Examples

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>

);

}

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

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

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

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

Anchor to Best practicesBest 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.

Was this page helpful?