Define a custom Shopify metaobject definition with typed fields using the metaobjectDefinitionCreate Admin GraphQL mutation
domain: shopify.dev · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
Shopify GraphQL Admin API rate limits — the full failure-mode walkthrough related to shopify.dev, checked against official docs, with linked verified routes.
Steps
Call `metaobjectDefinitionCreate(definition: { name: "Store Locator Entry", type: "$app:store_locator", fieldDefinitions: [...] })` — prefix the type with `$app:` to namespace it to your app and prevent conflicts with other apps or native types
In `fieldDefinitions`, declare each field with a `key`, `name`, human-readable `description`, and `type` (e.g., `single_line_text_field`, `json`, `number_integer`, `url`, `file_reference`); mark required fields with `validations` or `required: true` where supported
Set `access.admin` to `MERCHANT_READ_WRITE` and `access.storefront` to `PUBLIC_READ` if you want entries to be queryable via the Storefront API
Enable `displayNameKey` to specify which field's value should be used as the display name for entries in the Shopify admin metaobject browser
After creating the definition, create entries with `metaobjectCreate(metaobject: { type: "$app:store_locator", fields: [{ key: "name", value: "Paris Store" }, ...] })`
Query entries via the Storefront API with `metaobjects(type: "$app:store_locator", first: 10) { nodes { fields { key value } } }` to confirm storefront access
Known gotchas
The `$app:` prefix reserves the type exclusively for your app — other apps cannot create entries of this type; omitting the prefix makes the type globally accessible but risks naming collisions
Metaobject definitions cannot have their field types changed after creation — you can add new fields or mark existing ones as inactive, but you cannot alter the type of an existing field definition
The `write_metaobject_definitions` scope is required to create definitions, while `write_metaobjects` is required to create entries — you need both scopes declared in your app
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?