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
Known 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
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp