---
title: Metafields API
description: The API for interacting with metafields.
api_version: 2026-04
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04-rc/target-apis/order-apis/metafields-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04-rc/target-apis/order-apis/metafields-api.md
---

# Metafields API

**Requires access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data) for some properties.:**

The API for interacting with metafields.

## OrderStatusApi

The API object provided to this and other `customer-account.order-status` extension targets.

* **appMetafields**

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

  **required**

  The metafields requested in the [`shopify.ui.extension.toml`](https://shopify.dev/docs/api/customer-account-ui-extensions/configuration) file. 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/custom-data/ownership#reserved-prefixes) for more information.

  [](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).

### SubscribableSignalLike

Represents a read-only value managed on the main thread that an extension can subscribe to. Example: Checkout uses this to manage the state of an object and communicate state changes to extensions running in a sandboxed web worker. This interface is compatible with \[Preact's ReadonlySignal]\(https://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709). Some fields are deprecated but still supported for backwards compatibility. In version 2025-10, \[\`StatefulRemoteSubscribable\`]\(https://github.com/Shopify/remote-dom/blob/03929aa8418a89d41d294005f219837582718df8/packages/async-subscription/src/types.ts#L17) was replaced with \`ReadonlySignalLike\`. Checkout will remove the old fields some time in the future.

* current

  ```ts
  T
  ```

* destroy

  ```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

A metafield associated with the shop or a resource on the checkout.

* metafield

  The metadata information.

  ```ts
  AppMetafield
  ```

* target

  The target that is associated to the metadata. {% 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 metadata attached to a resource.

* key

  The key name of a metafield.

  ```ts
  string
  ```

* namespace

  The namespace for a metafield.

  ```ts
  string
  ```

* type

  The metafield's type name.

  ```ts
  string
  ```

* value

  The value of a metafield.

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

* valueType

  The metafield’s information type.

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

### AppMetafieldEntryTarget

The metafield owner.

* id

  The numeric owner ID that is associated with the metafield.

  ```ts
  string
  ```

* type

  The type of the metafield owner. {% 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'
      | 'order'
  ```