--- title: Metafields API description: The API for interacting with metafields. api_version: 2025-07 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/target-apis/platform-apis/metafields-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/target-apis/platform-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. ## StandardApi The base API object provided to `purchase` extension targets. * **appMetafields** **StatefulRemoteSubscribable\** **required** The metafields requested in the [`shopify.extension.toml`](https://shopify.dev/docs/api/checkout-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). * **metafields** **StatefulRemoteSubscribable\** **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](https://shopify.dev/docs/admin-api/graphql/reference/orders/order#metafield-2021-01) **Tip:** \> Cart metafields are only available on carts created via the Storefront API version \2023-04\ or later. ### 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. 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. ```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' | '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). ```ts 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). ```ts string ``` * value The information to be stored as metadata. ```ts string | number ``` * valueType The metafield’s information type. ```ts 'integer' | 'string' | 'json_string' ``` ## use​App​Metafields(**[filters](#useappmetafields-propertydetail-filters)**​) Returns the metafields configured with `shopify.extension.toml`. ### Parameters * **filters** **AppMetafieldFilters** **Default: {}** ### Returns * **AppMetafieldEntry\[]** ### AppMetafieldFilters * id ```ts AppMetafieldEntryTarget ``` * key ```ts Metafield ``` * 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. ```ts Metafield ``` * type ```ts AppMetafieldEntryTarget ``` ### 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' | '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). ```ts 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). ```ts string ``` * value The information to be stored as metadata. ```ts string | number ``` * valueType The metafield’s information type. ```ts 'integer' | 'string' | 'json_string' ``` ### 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. 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. ```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' ``` ## use​Metafield(**[filters](#usemetafield-propertydetail-filters)**​) Returns a single filtered `Metafield` or `undefined`. ### Parameters * **filters** **MetafieldFilter** **required** ### Returns * **Metafield | undefined** ### MetafieldFilter * key ```ts string ``` * namespace ```ts string ``` ### Metafield Metadata associated with the checkout. * key The name of the metafield. It must be between 3 and 30 characters in length (inclusive). ```ts 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). ```ts string ``` * value The information to be stored as metadata. ```ts string | number ``` * valueType The metafield’s information type. ```ts 'integer' | 'string' | 'json_string' ``` ## use​Metafields(**[filters](#usemetafields-propertydetail-filters)**​) Returns the current array of `metafields` applied to the checkout. You can optionally filter the list. ### Parameters * **filters** **MetafieldsFilters** ### Returns * **Metafield\[]** ### MetafieldsFilters * key ```ts string ``` * namespace ```ts string ``` ### Metafield Metadata associated with the checkout. * key The name of the metafield. It must be between 3 and 30 characters in length (inclusive). ```ts 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). ```ts string ``` * value The information to be stored as metadata. ```ts string | number ``` * valueType The metafield’s information type. ```ts 'integer' | 'string' | 'json_string' ``` ## CheckoutApi The API object provided to `purchase.checkout` extension targets. * **applyMetafieldChange** **(change: MetafieldChange) => 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`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/metafields#standardapi-propertydetail-metafields) property. **Note:** This method will return an error if the \cart instruction\ \\metafields.can\Set\Cart\Metafields\\ is false, or the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay. ### MetafieldChange ```ts MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange ``` ### MetafieldRemoveChange Removes a metafield. * key The name of the metafield to remove. ```ts string ``` * namespace The namespace of the metafield to remove. ```ts string ``` * type The type of the \`MetafieldRemoveChange\` API. ```ts 'removeMetafield' ``` ### MetafieldUpdateChange Updates a metafield. If a metafield with the provided key and namespace does not already exist, it gets created. * key The name of the metafield to update. ```ts string ``` * namespace The namespace of the metafield to add. ```ts string ``` * type The type of the \`MetafieldUpdateChange\` API. ```ts 'updateMetafield' ``` * value The new information to store in the metafield. ```ts string | number ``` * valueType The metafield’s information type. ```ts 'integer' | 'string' | 'json_string' ``` ### MetafieldRemoveCartChange Removes a cart metafield. * key The name of the metafield to remove. ```ts string ``` * namespace The namespace of the metafield to remove. ```ts string ``` * type The type of the \`MetafieldRemoveChange\` API. ```ts 'removeCartMetafield' ``` ### MetafieldUpdateCartChange Updates a cart metafield. If a metafield with the provided key and namespace does not already exist, it gets created. * metafield ```ts { key: string; namespace: string; value: string; type: string; } ``` * type The type of the \`MetafieldUpdateChange\` API. ```ts 'updateCartMetafield' ``` ### MetafieldChangeResult ```ts MetafieldChangeResultSuccess | MetafieldChangeResultError ``` ### MetafieldChangeResultSuccess * type The type of the \`MetafieldChangeResultSuccess\` API. ```ts '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. ```ts string ``` * type The type of the \`MetafieldChangeResultError\` API. ```ts 'error' ``` ## use​Apply​Metafields​Change() Returns a function to mutate the `metafields` property of the checkout. ### Returns * **(change: MetafieldChange) => Promise\** ### MetafieldChange ```ts MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange ``` ### MetafieldRemoveChange Removes a metafield. * key The name of the metafield to remove. ```ts string ``` * namespace The namespace of the metafield to remove. ```ts string ``` * type The type of the \`MetafieldRemoveChange\` API. ```ts 'removeMetafield' ``` ### MetafieldUpdateChange Updates a metafield. If a metafield with the provided key and namespace does not already exist, it gets created. * key The name of the metafield to update. ```ts string ``` * namespace The namespace of the metafield to add. ```ts string ``` * type The type of the \`MetafieldUpdateChange\` API. ```ts 'updateMetafield' ``` * value The new information to store in the metafield. ```ts string | number ``` * valueType The metafield’s information type. ```ts 'integer' | 'string' | 'json_string' ``` ### MetafieldRemoveCartChange Removes a cart metafield. * key The name of the metafield to remove. ```ts string ``` * namespace The namespace of the metafield to remove. ```ts string ``` * type The type of the \`MetafieldRemoveChange\` API. ```ts 'removeCartMetafield' ``` ### MetafieldUpdateCartChange Updates a cart metafield. If a metafield with the provided key and namespace does not already exist, it gets created. * metafield ```ts { key: string; namespace: string; value: string; type: string; } ``` * type The type of the \`MetafieldUpdateChange\` API. ```ts 'updateCartMetafield' ``` ### MetafieldChangeResult ```ts MetafieldChangeResultSuccess | MetafieldChangeResultError ``` ### MetafieldChangeResultSuccess * type The type of the \`MetafieldChangeResultSuccess\` API. ```ts '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. ```ts string ``` * type The type of the \`MetafieldChangeResultError\` API. ```ts 'error' ``` Examples ### 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. ##### React ```jsx import { reactExtension, Text, useAppMetafields, useCartLineTarget, } from '@shopify/ui-extensions-react/checkout'; export default reactExtension( 'purchase.checkout.cart-line-item.render-after', () => , ); function Extension() { const { merchandise: {id: productVariantId}, } = useCartLineTarget(); const [energyRating] = useAppMetafields({ namespace: '$app', key: 'energy-rating', type: 'product', }).filter( (entry) => entry.target.id === productVariantId, ); return ( energyRating && ( Energy rating:{' '} {energyRating.metafield.value} ) ); } ``` ##### JavaScript ```js import { extension, Text, } from '@shopify/ui-extensions/checkout'; export default extension( 'purchase.checkout.cart-line-item.render-after', (root, api) => { const productVariantId = api.target.current.merchandise.id; const filterMetafields = (entries) => { const [energyRating] = entries.filter( (entry) => entry.metafield.namespace === '$app' && entry.metafield.key === 'energy-rating' && entry.target.type === 'product' && entry.target.id === productVariantId, ); return energyRating; }; const render = (energyRating) => { if (energyRating) { root.replaceChildren( root.createComponent( Text, {}, `Energy rating: ${energyRating.metafield.value}`, ), ); } }; render( filterMetafields(api.appMetafields.current), ); api.appMetafields.subscribe((entries) => { render(filterMetafields(entries)); }); }, ); ``` ##### TOML ```toml # other configs omitted [[extensions.metafields]] # tip: you can use $app:some-namespace to further segment your data namespace = "$app" key = "energy-rating" ``` ## Related [Reference - Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets) [Reference - Components](https://shopify.dev/docs/api/checkout-ui-extensions/components) [Reference - Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) [Learn - Tutorials](https://shopify.dev/apps/checkout)