Choose a version:

Metafields

Requires access to protected customer data for some properties.

The API for interacting with metafields.

Anchor to standardapiStandardApi

The base API object provided to purchase extension targets.

Anchor to appMetafields appMetafields <[]> 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.

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 for more information.

Requires access to protected customer data.
Anchor to metafields metafields <[]> required: The metafields that apply to the current checkout.

Metafields are stored locally on the client and are applied to the order object after the checkout completes.

These metafields are shared by all extensions running on checkout, and persist for as long as the customer is working on this checkout.

Once the order is created, you can query these metafields using the GraphQL Admin API

Caution
metafields is deprecated. Use appMetafields with cart metafields instead.
Caution: <code>metafields</code> is deprecated. Use <code>appMetafields</code> with cart metafields instead.
Deprecated
Use appMetafields with cart metafields instead.

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

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

metafield
The metadata information.
```
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`.
```
AppMetafieldEntryTarget
```

AppMetafield

Represents a custom metadata attached to a resource.

key
The key name of a metafield.
```
string
```
namespace
The namespace for a metafield. 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.
```
string
```
type
The metafield's type name.
```
string
```
value
The value of a metafield.
```
string
```

valueType

The metafield’s information type.

'boolean' | 'float' | 'integer' | 'json_string' | 'string'

AppMetafieldEntryTarget

The metafield owner.

id
The numeric owner ID that is associated with the metafield.
```
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`.
```
| 'customer'
    | 'product'
    | 'shop'
    | 'shopUser'
    | 'variant'
    | 'company'
    | 'companyLocation'
    | 'cart'
```

Metafield

Metadata associated with the checkout.

key
The name of the metafield. It must be between 3 and 30 characters in length (inclusive).
```
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. This must be between 2 and 20 characters in length (inclusive).
```
string
```
value
The information to be stored as metadata. Always stored as a string, regardless of the metafield's type.
```
string | number
```
valueType
The metafield’s information type.
```
'integer' | 'string' | 'json_string'
```

Anchor to useAppMetafields
useAppMetafields(
filters
)

Returns the metafields configured with shopify.extension.toml.

Anchor to useAppMetafields-parametersParameters

Anchor to filters filters Default: {}

Anchor to useAppMetafields-returnsReturns

[]

AppMetafieldFilters

id
```
string
```
key
```
string
```
namespace
To filter for app owned metafields, use the `$app` format. The fully qualified reserved namespace format such as `app--{your-app-id}[--{optional-namespace}]` is not supported. See [app owned metafields](/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.
```
string
```

type

'customer' | 'product' | 'shop' | 'shopUser' | 'variant' | 'company' | 'companyLocation' | 'cart'

AppMetafieldEntry

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

metafield
The metadata information.
```
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`.
```
AppMetafieldEntryTarget
```

AppMetafield

Represents a custom metadata attached to a resource.

key
The key name of a metafield.
```
string
```
namespace
The namespace for a metafield. 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.
```
string
```
type
The metafield's type name.
```
string
```
value
The value of a metafield.
```
string
```

valueType

The metafield’s information type.

'boolean' | 'float' | 'integer' | 'json_string' | 'string'

AppMetafieldEntryTarget

The metafield owner.

id
The numeric owner ID that is associated with the metafield.
```
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`.
```
| 'customer'
    | 'product'
    | 'shop'
    | 'shopUser'
    | 'variant'
    | 'company'
    | 'companyLocation'
    | 'cart'
```

Anchor to useMetafield
useMetafield(
filters
)

Returns a single filtered Metafield or undefined.

Caution

useMetafield is deprecated. Use useAppMetafields with cart metafields instead.

Anchor to useMetafield-parametersParameters

Anchor to filters filters required

Anchor to useMetafield-returnsReturns

| undefined

MetafieldFilter

key
```
string
```
namespace
```
string
```

Metafield

Metadata associated with the checkout.

key
The name of the metafield. It must be between 3 and 30 characters in length (inclusive).
```
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. This must be between 2 and 20 characters in length (inclusive).
```
string
```
value
The information to be stored as metadata. Always stored as a string, regardless of the metafield's type.
```
string | number
```
valueType
The metafield’s information type.
```
'integer' | 'string' | 'json_string'
```

Anchor to useMetafields
useMetafields(
filters
)

Returns the current array of metafields applied to the checkout. You can optionally filter the list.

Caution

useMetafields is deprecated. Use useAppMetafields with cart metafields instead.

Anchor to useMetafields-parametersParameters

Anchor to filters filters

Anchor to useMetafields-returnsReturns

[]

MetafieldsFilters

key
```
string
```
namespace
```
string
```

Metafield

Metadata associated with the checkout.

key
The name of the metafield. It must be between 3 and 30 characters in length (inclusive).
```
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. This must be between 2 and 20 characters in length (inclusive).
```
string
```
value
The information to be stored as metadata. Always stored as a string, regardless of the metafield's type.
```
string | number
```
valueType
The metafield’s information type.
```
'integer' | 'string' | 'json_string'
```

Anchor to checkoutapiCheckoutApi

The API object provided to purchase.checkout extension targets.

Anchor to applyMetafieldChange applyMetafieldChange (change: ) => Promise<> required: Performs an update on a piece of metadata attached to the checkout. If successful, this mutation results in an update to the value retrieved through the metafields property.

Cart metafields will be copied to order metafields at order creation time if there is a matching order metafield definition with the cart to order copyable capability enabled.

Caution
MetafieldRemoveChange and MetafieldUpdateChange are deprecated. Use cart metafields with MetafieldRemoveCartChange and MetafieldUpdateCartChange instead. If MetafieldUpdateChange writes a metafield with the same namespace and key as a cart metafield that’s configured to copy, the cart metafield won’t be copied.
Caution: <code>MetafieldRemoveChange</code> and <code>MetafieldUpdateChange</code> are deprecated. Use cart metafields with <code>MetafieldRemoveCartChange</code> and <code>MetafieldUpdateCartChange</code> instead. If <code>MetafieldUpdateChange</code> writes a metafield with the same namespace and key as a cart metafield that’s configured to copy, the cart metafield won’t be copied.
Note
This method will return an error if the cart instruction metafields.canSetCartMetafields is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
Note: This method will return an error if the <a href="/docs/api/checkout-ui-extensions/apis/cart-instructions#standardapi-propertydetail-instructions">cart instruction</a> <code>metafields.canSetCartMetafields</code> is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.

MetafieldChange

MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange

MetafieldRemoveChange

Removes a metafield. This change type is deprecated and will be removed in a future API version. Use `MetafieldRemoveCartChange` instead.

key
The name of the metafield to remove.
```
string
```
namespace
The namespace of the metafield to remove.
```
string
```
type
The type of the `MetafieldRemoveChange` API.
```
'removeMetafield'
```

MetafieldUpdateChange

Updates a metafield. If a metafield with the provided key and namespace does not already exist, it gets created. This change type is deprecated and will be removed in a future API version. Use `MetafieldUpdateCartChange` instead.

key
The name of the metafield to update.
```
string
```
namespace
The namespace of the metafield to add.
```
string
```
type
The type of the `MetafieldUpdateChange` API.
```
'updateMetafield'
```
value
The new information to store in the metafield.
```
string | number
```
valueType
The metafield’s information type.
```
'integer' | 'string' | 'json_string'
```

MetafieldRemoveCartChange

Removes a cart metafield.

key
The name of the metafield to remove.
```
string
```
namespace
The namespace of the metafield to remove.
```
string
```
type
The type of the `MetafieldRemoveChange` API.
```
'removeCartMetafield'
```

MetafieldUpdateCartChange

Updates a cart metafield. If a metafield with the provided key and namespace does not already exist, it gets created.

metafield

{ key: string; namespace?: string; value: string; type: string; }

type
The type of the `MetafieldUpdateChange` API.
```
'updateCartMetafield'
```

MetafieldChangeResult

MetafieldChangeResultSuccess | MetafieldChangeResultError

MetafieldChangeResultSuccess

type
The type of the `MetafieldChangeResultSuccess` API.
```
'success'
```

MetafieldChangeResultError

message
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
```
string
```
type
The type of the `MetafieldChangeResultError` API.
```
'error'
```

Anchor to useApplyMetafieldsChange
useApplyMetafieldsChange()

Returns a function to mutate the metafields property of the checkout.

Anchor to useApplyMetafieldsChange-returnsReturns

(change: ) => Promise<>

MetafieldChange

MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange

MetafieldRemoveChange

Removes a metafield. This change type is deprecated and will be removed in a future API version. Use `MetafieldRemoveCartChange` instead.

key
The name of the metafield to remove.
```
string
```
namespace
The namespace of the metafield to remove.
```
string
```
type
The type of the `MetafieldRemoveChange` API.
```
'removeMetafield'
```

MetafieldUpdateChange

Updates a metafield. If a metafield with the provided key and namespace does not already exist, it gets created. This change type is deprecated and will be removed in a future API version. Use `MetafieldUpdateCartChange` instead.

key
The name of the metafield to update.
```
string
```
namespace
The namespace of the metafield to add.
```
string
```
type
The type of the `MetafieldUpdateChange` API.
```
'updateMetafield'
```
value
The new information to store in the metafield.
```
string | number
```
valueType
The metafield’s information type.
```
'integer' | 'string' | 'json_string'
```

MetafieldRemoveCartChange

Removes a cart metafield.

key
The name of the metafield to remove.
```
string
```
namespace
The namespace of the metafield to remove.
```
string
```
type
The type of the `MetafieldRemoveChange` API.
```
'removeCartMetafield'
```

MetafieldUpdateCartChange

Updates a cart metafield. If a metafield with the provided key and namespace does not already exist, it gets created.

metafield

{ key: string; namespace?: string; value: string; type: string; }

type
The type of the `MetafieldUpdateChange` API.
```
'updateCartMetafield'
```

MetafieldChangeResult

MetafieldChangeResultSuccess | MetafieldChangeResultError

MetafieldChangeResultSuccess

type
The type of the `MetafieldChangeResultSuccess` API.
```
'success'
```

MetafieldChangeResultError

message
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
```
string
```
type
The type of the `MetafieldChangeResultError` API.
```
'error'
```

Examples

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

import {useAppMetafields} from '@shopify/ui-extensions/checkout/preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

const [energyRating] = useAppMetafields({

namespace: '$app',

key: 'energy-rating',

type: 'product',

}).filter(

(entry) =>

entry.target.id ===

shopify.target.value.merchandise.id,

);

return (

energyRating && (

<s-text>

Energy rating:{' '}

{energyRating.metafield.value}

</s-text>

)

);

}

Examples

Use app owned metafields

Description

Use the `$app` format to request metafields that are owned by your app in your extension configuration file. Your app exclusively controls structure, data, permissions and optional features for this type of metafield. See [app owned metafields](/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.

Preact

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

import {useAppMetafields} from '@shopify/ui-extensions/checkout/preact';

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

function Extension() {
  const [energyRating] = useAppMetafields({
    namespace: '$app',
    key: 'energy-rating',
    type: 'product',
  }).filter(
    (entry) =>
      entry.target.id ===
      shopify.target.value.merchandise.id,
  );

  return (
    energyRating && (
      <s-text>
        Energy rating:{' '}
        {energyRating.metafield.value}
      </s-text>
    )
  );
}

TOML

# other configs omitted

[[extensions.metafields]]
# tip: you can use $app:some-namespace to further segment your data
namespace = "$app"
key = "energy-rating"