Read shop and cart metafields and write cart metafields from inside a Shopify Checkout UI Extension using the purchase.checkout.block.render target

In-depth guide

Steps

1. In your extension TOML, declare the metafields you need to read under `[[extensions.metafields]]` with `namespace` and `key`; these are pre-fetched and available via the `useAppMetafields` hook at runtime
2. Use the `useAppMetafields()` hook in your extension component to access the declared metafield values — this works for shop, product, and variant metafields depending on what you declared
3. To write a cart metafield, call `applyMetafieldChange({ type: 'updateCartMetafield', namespace, key, valueType, value })` obtained from `useApplyMetafieldChange()`; this is available on checkout targets but not on thank-you or order-status page targets
4. In the extension TOML, configure any merchant-editable settings under `[extensions.settings]` with typed `fields` entries; read these in the extension with the `useSettings()` hook
5. Handle the `instructions.metafields.canSetCartMetafields` flag (available in API 2025-01+) before calling applyMetafieldChange to gracefully degrade if cart metafield writes are unavailable in the current checkout context
6. Test metafield reads and writes using the checkout extension development server (`shopify app dev`) with the browser preview URL