Call the `metaobjectDefinitionCreate` Admin GraphQL mutation to define a new metaobject type, providing a `type` identifier (lowercase underscore slug), a display name, and an array of `fieldDefinitions` — each with a `key`, `name`, `type` (e.g., `single_line_text_field`, `file_reference`, `boolean`), and optional validations.
Set `access.storefront` to `PUBLIC_READ` on the definition if the entries need to be queryable via the Storefront API for use in headless storefronts or themes.
Create individual entries by calling `metaobjectCreate`, providing the definition `type` and a `fields` array with each field's key and value.
To update an entry, call `metaobjectUpdate` with the entry's GID and the updated field values — only provide fields that need to change; omitted fields retain their current values.
Query entries in the Storefront API using the `metaobjects` query, filtering by type; query them in the Admin API using `metaobjects` with a type filter or by GID using `metaobject`.
To expose metaobject entry references on products or other resources, create a metafield of type `metaobject_reference` on the product pointing to the entry's GID.
Known gotchas
The metaobject `type` identifier is permanent once created — it cannot be renamed without creating a new definition and migrating all entries. Choose a clear, namespaced type slug (e.g., `acme_store_locator`) before creating in production.
Storefront API access for metaobjects requires both `access.storefront: PUBLIC_READ` on the definition AND a Shopify Storefront API token with `unauthenticated_read_metaobjects` scope or equivalent. Missing either will return null.
Metaobject entries do not have automatic versioning or rollback. Destructive field definition changes (deleting a field from the definition) permanently remove that field's data from all existing entries — test definition changes on a dev store first.
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