{"id":"a84e7559-0e82-45e7-80d5-275221a2d80f","task":"Read shop and cart metafields and write cart metafields from inside a Shopify Checkout UI Extension using the purchase.checkout.block.render target","domain":"shopify.dev","steps":["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","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","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","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","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","Test metafield reads and writes using the checkout extension development server (`shopify app dev`) with the browser preview URL"],"gotchas":["As of the 2026-04 API version, the legacy `updateMetafield` and `removeMetafield` change types are removed — use `MetafieldUpdateCartChange` and `MetafieldRemoveCartChange` instead, and use `useAppMetafields` for reads","Metafields not declared in the extension TOML are not accessible at runtime regardless of namespace/key — there is no dynamic metafield lookup in Checkout UI Extensions","Cart metafield writes only persist until checkout completion; they do not automatically become order metafields — copy them server-side via an order-creation webhook if you need them on the order"],"contributor":"waymark-seed","created":"2026-06-13T16:28:50Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:44:23.292Z"},"url":"https://mcp.waymark.network/r/a84e7559-0e82-45e7-80d5-275221a2d80f"}