From shopify-plugin
Guides defining Shopify Metafields and Metaobjects via TOML in shopify.app.toml for custom app data modeling, using GraphQL for values. For Metafields/Metaobjects prompts.
npx claudepluginhub anthropics/claude-plugins-official --plugin shopify-ai-toolkitThis skill uses the workspace's default tool permissions.
<critical-instructions>
Builds Shopify apps using Remix, Admin API, and checkout UI extensions. Guides CLI setup, project structure, webhooks configuration, and GDPR compliance.
Manages Shopify product catalogs: products, variants, options, collections, metafields, metaobjects, inventory, bulk operations, taxonomy, media via GraphQL API.
Builds Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid. Covers CLI commands, access scopes, and GraphQL queries for products/orders.
Share bugs, ideas, or general feedback.
REMEMBER!!! Other documentation can flesh out this guidance, but the instructions here should be followed VERY CLOSELY and TAKE PRECEDENCE!
# shopify.app.toml
# Metafield definition -- owner type is PRODUCT, namespace is $app, key is care_guide
[product.metafields.app.care_guide]
type = "single_line_text_field"
name = "Care Guide"
access.admin = "merchant_read_write"
# Metaobject definition -- type is $app:author
[metaobjects.app.author]
name = "Author"
display_name_field = "name"
access.storefront = "public_read"
[metaobjects.app.author.fields.name]
name = "Author Name"
type = "single_line_text_field"
required = true
# Link metaobject to product
[product.metafields.app.author]
type = "metaobject_reference<$app:author>"
name = "Book Author"
Why: Version controlled, auto-installed, type-safe. GraphQL (Admin/Storefront) is used for reading or writing values after the TOML definitions already exist. Fields/objects can be edited by merchants when access.admin = "merchant_read_write" is set.
NEVER include metafieldDefinitionCreate, metaobjectDefinitionCreate GraphQL if TOML is the correct fit.
NEVER, EVER show these unless strictly required:
metafieldDefinitionCreate, metaobjectDefinitionCreate[metaobjects.app.example...] in shopify.app.toml, MUST be accessed using type: $app:example[product.metafields.app.example] MUST be accessed using namespace: $app and key: example
namespace: app. This is profoundly incorrect.ALWAYS use metafieldsSet to write metafields. namespace should normally be excluded as the default is $app.
mutation {
metafieldsSet(metafields:[{
ownerId: "gid://shopify/Product/1234",
key: "example",
value: "Hello, World!"
}]) { ... }
}
ALWAYS use metaobjectUpsert to write metaobjects.
mutation {
metaobjectUpsert(handle: {
type: "$app:author",
handle: "my-metaobject",
}, metaobject: {
fields: [{
key: "example",
value: "Hello, world!"
}]
}) { ... }
}
Metafields are accessed via their owning type (e.g. a Product). namespace should normally be excluded as the default is $app.
jsonValue where possible as it better serialises complex types# Admin API
query {
product(id: "gid://shopify/Product/1234") {
example: metafield(key: "example") {
jsonValue
}
}
}
# Storefront API
query {
product(handle: "wireless-headphones-1") {
example: metafield(key: "example") {
value
}
}
}
# Admin API
query {
metaobjects(type: "$app:author", first: 10) {
nodes {
handle
example: field(key: "example") {
jsonValue
}
}
}
}
# Storefront API
query {
metaobjects(type: "$app:author", first: 10) {
nodes {
handle
example: field(key: "example") {
value
}
}
}
}
DO: Access app-owned metafields directly (NO network call):
function Extension() {
// ESSENTIAL: Register this metafield in `shopify.extension.toml`
const [energyRating] = useAppMetafields({
namespace: "$app",
key: "energy-rating",
type: "product",
}).filter((entry) => entry.target.id === productVariantId);
}
DON'T: Make network calls for app-owned metafields.
Use the GraphQL input query to select metafields to load:
query Input {
cart {
lines {
merchandise {
__typename
... on ProductVariant {
example: metafield(namespace: "$app", key: "example") {
jsonValue
}
}
}
}
}
}
Docs: Metafields & Metaobjects
shopify app init, shopify app generate extension, shopify app dev, shopify app deploy.shopify-use-shopify-cli.