--- title: Metafields API description: The API for interacting with metafields. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/platform-apis/metafields-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/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. ### Support Targets (33) ### Supported targets * purchase.​address-autocomplete.​format-suggestion * purchase.​address-autocomplete.​suggest * purchase.​checkout.​actions.​render-before * purchase.​checkout.​block.​render * purchase.​checkout.​cart-line-item.​render-after * purchase.​checkout.​cart-line-list.​render-after * purchase.​checkout.​chat.​render * purchase.​checkout.​contact.​render-after * purchase.​checkout.​delivery-address.​render-after * purchase.​checkout.​delivery-address.​render-before * purchase.​checkout.​footer.​render-after * purchase.​checkout.​header.​render-after * purchase.​checkout.​payment-method-list.​render-after * purchase.​checkout.​payment-method-list.​render-before * purchase.​checkout.​pickup-location-list.​render-after * purchase.​checkout.​pickup-location-list.​render-before * purchase.​checkout.​pickup-location-option-item.​render-after * purchase.​checkout.​pickup-point-list.​render-after * purchase.​checkout.​pickup-point-list.​render-before * purchase.​checkout.​reductions.​render-after * purchase.​checkout.​reductions.​render-before * purchase.​checkout.​shipping-option-item.​details.​render * purchase.​checkout.​shipping-option-item.​render-after * purchase.​checkout.​shipping-option-list.​render-after * purchase.​checkout.​shipping-option-list.​render-before * purchase.​thank-you.​announcement.​render * purchase.​thank-you.​block.​render * purchase.​thank-you.​cart-line-item.​render-after * purchase.​thank-you.​cart-line-list.​render-after * purchase.​thank-you.​chat.​render * purchase.​thank-you.​customer-information.​render-after * purchase.​thank-you.​footer.​render-after * purchase.​thank-you.​header.​render-after ## StandardApi The base API object provided to `purchase` extension targets. * **appMetafields** **SubscribableSignalLike\** **required** The metafields requested in the [`shopify.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/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}]` isn't 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 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 ``` * 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. * 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. {% 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 \[metafield]\(/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'\`. ```ts 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]\(/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information. ```ts string ``` * type The metafield's \[type name]\(/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. ```ts 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. ```ts 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. ```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 you can trace where the data comes from. * 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 \[Storefront API]\(/docs/api/storefront). ```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. - \`'shopUser'\`: A staff member or collaborator account on the shop. - \`'variant'\`: A specific variant of a product. - \`'company'\`: A \[B2B]\(/docs/apps/build/b2b) company associated with the order. - \`'companyLocation'\`: A location belonging to a \[B2B]\(/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]\(/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' ``` ## use​App​Metafields(**[filters](#useappmetafields-propertydetail-filters)**​) Returns the metafields configured with `shopify.extension.toml`. ### Parameters * **filters** **AppMetafieldFilters** **Default: {}** ### Returns * **AppMetafieldEntry\[]** ### AppMetafieldFilters * id ```ts string ``` * key ```ts 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. ```ts string ``` * type ```ts 'customer' | 'product' | 'shop' | 'shopUser' | 'variant' | 'company' | 'companyLocation' | 'cart' ``` ## CheckoutApi The API object provided to `purchase.checkout` extension targets. * **applyMetafieldChange** **(change: MetafieldChange) => Promise\** **required** Creates, updates, or removes a cart metafield on the checkout. On success, the [`metafields`](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/apis/metafields#standardapi-propertydetail-metafields) property updates to reflect the change. Cart metafields are copied to order metafields at order creation time if there's a matching order metafield definition with the [`cart to order copyable`](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#cart-to-order-copyable) capability enabled. **Note:** This method returns 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 or Google Pay. ### MetafieldChange The input for \`applyMetafieldChange()\`. Use the \`type\` property to specify the operation. - \`MetafieldRemoveCartChange\` (\`type: 'removeCartMetafield'\`): Removes an existing cart \[metafield]\(/docs/apps/build/custom-data/metafields). - \`MetafieldUpdateCartChange\` (\`type: 'updateCartMetafield'\`): Creates or updates a cart metafield. ```ts MetafieldRemoveCartChange | MetafieldUpdateCartChange ``` ### MetafieldRemoveCartChange Removes a cart \[metafield]\(/docs/apps/build/custom-data/metafields). Pass this to \`applyMetafieldChange()\` to delete a metafield by key and namespace. * key The name of the metafield to remove. ```ts string ``` * namespace The namespace of the metafield to remove. ```ts string ``` * type Identifies this as a cart metafield removal. Set this when creating a change to delete an existing metafield by key and namespace. ```ts 'removeCartMetafield' ``` ### MetafieldUpdateCartChange Creates or updates a cart \[metafield]\(/docs/apps/build/custom-data/metafields). Pass this to \`applyMetafieldChange()\` to set a metafield value. If a metafield with the provided key and namespace doesn't already exist, then it gets created. * metafield The metafield data to set on the cart. If a metafield with this key and namespace already exists, then its value is replaced. ```ts { key: string; namespace?: string; value: string; type: string; } ``` * type Identifies this as a cart metafield creation or update. Set this when creating a change to set a metafield value. ```ts 'updateCartMetafield' ``` ### MetafieldChangeResult The result of calling \`applyMetafieldChange()\`. Use the \`type\` property to determine whether the change succeeded or failed. ```ts MetafieldChangeResultSuccess | MetafieldChangeResultError ``` ### MetafieldChangeResultSuccess The result of a successful metafield change. The \`type\` property is \`'success'\`. * type Indicates that the metafield change was applied successfully. ```ts 'success' ``` ### MetafieldChangeResultError The result of a failed metafield change. Check the \`message\` property for details about what went wrong. * message A message that explains the error. This message is useful for debugging. It isn't localized and shouldn't be displayed to the buyer. ```ts string ``` * type Indicates that the metafield change couldn't be applied. Check the \`message\` property for details. ```ts 'error' ``` ## use​Apply​Metafields​Change() Returns a function to mutate the `metafields` property of the checkout. ### Returns * **(change: MetafieldChange) => Promise\** 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. ##### Preact ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useAppMetafields} from '@shopify/ui-extensions/checkout/preact'; export default function extension() { render(, 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 && ( Energy rating:{' '} {energyRating.metafield.value} ) ); } ``` ##### 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)