From shopify-pack
Model custom data with Shopify metafields and metaobjects via the GraphQL Admin API. Use when adding custom fields to products/orders, creating custom content types, or building structured data models beyond Shopify's default schema. Trigger with phrases like "shopify metafields", "shopify metaobjects", "custom data shopify", "shopify custom fields", "metafield definition".
npx claudepluginhub flight505/skill-forge --plugin shopify-packThis skill is limited to using the following tools:
Metafields attach key-value custom data to existing resources (products, variants, orders, customers). Metaobjects define entirely new content types with custom schemas. Together they replace the need for external databases for most custom data needs.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Share bugs, ideas, or general feedback.
Metafields attach key-value custom data to existing resources (products, variants, orders, customers). Metaobjects define entirely new content types with custom schemas. Together they replace the need for external databases for most custom data needs.
shopify-install-auth setupread_metaobjects, write_metaobjects, read_metaobject_definitions, write_metaobject_definitionsread_products/write_products for product metafields, etc.Use metafieldDefinitionCreate with namespace, key, type, and ownerType:
await client.request(METAFIELD_DEFINITION_CREATE, {
variables: {
definition: {
namespace: "custom",
key: "care_instructions",
name: "Care Instructions",
type: "multi_line_text_field", // See references/metafield-types.md
ownerType: "PRODUCT",
pin: true, // Show in admin UI
},
},
});
// Always check userErrors — Shopify returns 200 even on validation failures
await client.request(METAFIELDS_SET, {
variables: {
metafields: [
{
ownerId: "gid://shopify/Product/123456",
namespace: "custom",
key: "care_instructions",
value: "Machine wash cold.\nTumble dry low.",
type: "multi_line_text_field",
},
// Up to 25 metafields per call
],
},
});
Define a custom content type (e.g., "Designer" with typed fields):
await client.request(METAOBJECT_DEFINITION_CREATE, {
variables: {
definition: {
type: "$app:designer",
displayNameKey: "name",
fieldDefinitions: [
{ key: "name", name: "Name", type: "single_line_text_field" },
{ key: "bio", name: "Bio", type: "multi_line_text_field" },
{ key: "photo", name: "Photo", type: "file_reference" },
],
access: { storefront: "PUBLIC_READ" },
},
},
});
await client.request(METAOBJECT_CREATE, {
variables: {
metaobject: {
type: "$app:designer",
handle: "jane-doe",
fields: [
{ key: "name", value: "Jane Doe" },
{ key: "bio", value: "Award-winning textile designer." },
],
},
},
});
See metafield-types.md for all types, toml-config.md for app config, and bulk-metafield-ops.md for bulk operations.
| Error | Cause | Solution |
|---|---|---|
TAKEN | Namespace + key already exists on this owner type | Use metafieldDefinitionUpdate or choose a different key |
INVALID_TYPE | Type string not in Shopify's registry | Check metafield-types.md |
INVALID_VALUE | Value doesn't match declared type | Cast value to correct format before setting |
TOO_LONG | Value exceeds type limit (512KB for text types) | Truncate or switch to multi_line_text_field |
Define a "care_instructions" metafield on the PRODUCT owner type, then bulk-set values across hundreds of products in batches of 25.
See Bulk Metafield Ops for the batch set/delete operations.
You need to store a color swatch, a date range, or a product reference. Pick the correct type from Shopify's type registry.
See Metafield Types for the complete type list with value format examples.
Define metafield and metaobject schemas in shopify.app.toml so they deploy automatically with the app instead of making API calls.
See TOML Config for the app configuration syntax.