How to read a regular customer metafield value from checkout ui extension

Retired Boards Appdev Extensions

Topic summary

Issue: A developer struggled to read customer metafield values in a Shopify checkout UI extension. While useAppMetafields successfully detected whether metafields were defined, accessing metafield?.value returned undefined.

Key Solutions:

  • Configuration: Metafields must be declared in the extension’s TOML file and the server restarted afterward
  • Data Structure: useAppMetafields returns an array, so values are accessed via appMetafields[0].value
  • TOML Syntax: For multiple extension targets, use [[extensions.targeting.metafields]] instead of [[extensions.metafields]]
  • Placement: Each metafield block should be positioned directly under its associated target block in the TOML file

Example TOML Structure:

[[extensions.targeting]]
target = "..."
[[extensions.targeting.metafields]]
namespace = "custom"
key = "key1"

Additional Notes:

  • Metafield values can be viewed in browser console logs even when storefront read access is disabled
  • The product/customer must have actual values set in the metafield for testing

Status: Resolved through proper TOML configuration and correct array indexing.

Summarized with AI on November 17. AI used: claude-sonnet-4-5-20250929.
6

In my case, I had multiple extension targets and multiple metafields defined in the toml file. I reviewed new guidance at https://shopify.dev/docs/apps/app-extensions/configuration .
What fixed the problem for my app was modification to the toml file to:

a) use [[extensions.targeting.metafields]] instead of [[extensions.metafields]] and

b) place each metafield block under the associated target block.

Example:

[[extensions.targeting]]
module = “./src/Checkout1.jsx”
target = “purchase.checkout.shipping-option-list.render-before”

[[extensions.targeting.metafields]]
key = “key1”
namespace = “custom”

[[extensions.targeting]]
module = “./src/Checkout2.jsx”
target = “purchase.checkout.shipping-option-list.render-after”

[[extensions.targeting.metafields]]
key = “key2”
namespace = “custom”

1 Like