shopify-metafields

Shopify Metafields

Overview

Metafields let you attach structured custom data to Shopify resources — products, variants, orders, customers, collections, and pages — without building a separate database. Metafield definitions enforce type validation (text, number, date, URL, JSON, file, product reference, etc.) and make metafields available in the Liquid template editor and Storefront API. Metaobjects extend this concept to create reusable, standalone custom data structures.

When to Use This Skill

• When products need additional attributes beyond Shopify's default fields (care instructions, dimensions, certifications)
• When storing per-customer data such as loyalty tier, subscription status, or B2B account number
• When building content-managed sections in a theme using metafield references (FAQs, size guides, feature callouts)
• When attaching order-level custom data from checkout (gift message, delivery instructions)
• When creating reusable structured content entries with Metaobjects (team members, press mentions, specs)

Core Instructions

1. Create metafield definitions via the Admin API

   Definitions enforce type and make metafields storefront-accessible:

   // Create a metafield definition for product care instructions
   const response = await adminClient.request(`
     mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
       metafieldDefinitionCreate(definition: $definition) {
         createdDefinition {
           id
           name
           namespace
           key
           type { name }
         }
         userErrors { field message code }
       }
     }
   `, {
     variables: {
       definition: {
         name: "Care Instructions",
         namespace: "custom",
         key: "care_instructions",
         type: "multi_line_text_field",
         ownerType: "PRODUCT",
         description: "Washing and care instructions for the product",
         visibleToStorefrontApi: true,
         // Optional: pin to product admin UI (use pinnedPosition in API version 2023-10+)
         pinnedPosition: 1,
       },
     },
   });