Define a metafield definition first via POST /admin/api/2024-01/metafield_definitions.json specifying name, namespace, key, type (e.g. single_line_text_field, json), and owner_type (e.g. PRODUCT)
Write a metafield to a specific product via POST /admin/api/2024-01/products/{product_id}/metafields.json with namespace, key, value, and type fields in the request body
Read all metafields for a product via GET /admin/api/2024-01/products/{product_id}/metafields.json, optionally filtering by namespace
To update an existing metafield, issue PUT /admin/api/2024-01/metafields/{metafield_id}.json with the new value; the type cannot be changed after creation
For bulk metafield writes on many resources, use the GraphQL productUpdate mutation with a metafields array input, or use the Bulk Operations API with metafieldsSet mutation
Retrieve metafield definitions to validate namespace/key combinations before writing, avoiding silent type coercion errors
Known gotchas
Metafield types are strictly enforced; writing a string to a number type field returns a validation error rather than coercing the value
Namespace and key together form a unique identifier per resource; writing the same namespace+key pair on the same resource updates the existing metafield, not creates a new one
Storefront visibility requires setting the metafield definition's access field; by default metafields written via Admin API are not exposed to Storefront API queries
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