Using metafields for custom data in checkout

Metafields are key-value pairs that you can use to store custom data on a Shopify resource. You can use metafields to store data that is specific to your checkout UI extension, such as the extension's configuration or the buyer's consent.

To access metafields in your checkout UI extension, use the Metafields API.

For a full tutorial on using metafields read and write custom data in your checkout UI extension, see Display custom data at checkout.

Anchor to Configuring metafieldsConfiguring metafields

To use metafields in your checkout UI extension, you need to configure them in your extension's .toml configuration file file.

To define a metafield that's available to your extension wherever it's rendered in the checkout, use theextensions.metafields property.

To define a metafield that your extension can access only from a specific extension target, use the extensions.targeting.metafields property.

Each entry takes a namespace and a key. From API version 2026-10, each entry can also include owner_type, which tells checkout which resource to load the metafield from.

The following example snippets use API version 2026-10. This one shows two metafields defined using these properties:

Anchor to App owned metafieldsApp owned metafields

When your app needs to control the data and visibility of the metafield, you can use app owned metafields. Using an app-owned metafield prevents other apps or merchants from accessing or modifying the data stored in the metafield.

Your extension can only access app-owned metafields that belong to its parent app.

The following example snippet shows a definition for an app-owned metafield:

Anchor to Supported owner typesSupported owner types

The following owner types are supported: