Create a metafield definition by calling the `metafieldDefinitionCreate` mutation with a `definition` input specifying `name`, `namespace`, `key`, `type` (e.g., `single_line_text_field`, `json`), and `ownerType` (e.g., `PRODUCT`, `CUSTOMER`).
Write a metafield value to a specific resource using the `metafieldsSet` mutation, passing an array of metafield inputs each containing `ownerId`, `namespace`, `key`, `value`, and `type`.
To read metafields back, query the resource (e.g., `product`) and include a `metafields(namespace: "...")` connection, selecting `key`, `value`, and `type`.
To update an existing metafield, call `metafieldsSet` again with the same `ownerId`, `namespace`, and `key` — this upserts the value.
To delete a metafield, use the `metafieldDelete` mutation with the metafield `id`.
If you need metafields accessible in Liquid storefronts, ensure the definition has `access.storefront` set to `PUBLIC_READ` when creating the definition.
Known gotchas
Namespace and key are immutable after a metafield definition is created — plan your schema carefully before writing production data.
The `type` field in `metafieldsSet` must exactly match the type declared in the definition; mismatches return a validation error rather than silently coercing.
App-owned namespaces (prefixed with the app's namespace) are only accessible by that app; using a shared namespace without a definition allows any app to read/write, which may expose data unintentionally.
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