Use the metaobjectDefinitionCreate Admin GraphQL mutation to define a new metaobject type; specify type (a unique string like 'store_location'), name, and fieldDefinitions array with key, name, type (e.g., 'single_line_text_field', 'number_decimal', 'url', 'product_reference'), and validations if needed
Set capabilities.publishable.enabled: true in the definition if entries need to be published/unpublished independently (useful for CMS-style content); omit for always-visible data
Create entries with metaobjectCreate, passing type and fields array with key-value pairs; values are always strings — for reference types pass the GID of the referenced resource
Query metaobjects via the Storefront API using the metaobjects query with type and first arguments; use edges { node { fields { key value } } } to retrieve entries with their fields
To expose a metaobject field on a product page, add a product metafield (type 'metaobject_reference') pointing to a metaobject entry and query it via Storefront API product.metafield(namespace, key) { reference { ... on Metaobject { fields { key value } } } }
Update entries with metaobjectUpdate passing the metaobject GID and updated fields; delete with metaobjectDelete
Known gotchas
Metaobject type strings must be globally unique within the shop and cannot be changed after creation; plan your type naming convention before creating definitions in production
Field type determines validation and how values are returned in the Storefront API — using 'single_line_text_field' for a URL works but loses URL validation; use 'url' type for URLs so validation runs server-side
The Storefront API requires metaobject definitions to have storefront access explicitly enabled; if the metaobjects query returns no results even after creating entries, check the definition's access settings in the Admin or via metaobjectDefinitionUpdate
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