Shopify Custom Data

1---2name: shopify-custom-data3description: "MUST be used first when prompts mention Metafields or Metaobjects. Use Metafields and Metaobjects to model and store custom data for your app. Metafields extend built-in Shopify data types like products or customers, Metaobjects are custom data types that can be used to store bespoke data structures. Metafield and Metaobject definitions provide a schema and configuration for values to follow."4compatibility: Claude Code, Claude Desktop, Cursor5metadata:6  author: Shopify7  version: "1.0"8---9 10## Required Tool Calls (do not skip)11 12You have a `bash` tool. Every response must use it — in this order:131. Call `bash` with `node scripts/search_docs.mjs "<operation or type name>"` — search before writing code142. Write the code using the search results153. Call `bash` with `node scripts/validate.mjs --code '...' --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION --artifact-id YOUR_ARTIFACT_ID --revision REVISION_NUMBER` — validate before returning16   (Always include these flags. Use your actual model name for YOUR_MODEL_NAME; use claude-code/cursor/etc. for YOUR_CLIENT_NAME. For YOUR_ARTIFACT_ID, generate a stable random ID per code block and reuse it across validation retries. For REVISION_NUMBER, start at 1 and increment on each retry of the same artifact.)174. If validation fails: search for the error type, fix, re-validate (max 3 retries)185. Return code only after validation passes19 20**You must run both search_docs.mjs and validate.mjs in every response. Do not return code to the user without completing step 3.**21 22---23 24<critical-instructions>25# Best Practise for working with Metafields and Metaobjects26 27# ESSENTIAL RULES28- **ALWAYS** show creating metafield/metaobject definitions, then writing values, then retrieving values.29- **NEVER** show or offer alternate approaches to the same problem if not explicitly requested. It will only increase the user's confusion.30- Keep examples minimal -- avoid unnecessary prose and comments31- Remember the audience for this guidance is app developers -- they do not have access to the Shopify Admin site32- Follow this guidance meticulously and thoroughly33 34REMEMBER!!! Other documentation can flesh out this guidance, but the instructions here should be followed VERY CLOSELY and TAKE PRECEDENCE!35 36# ALWAYS: First, create definitions37 38## with TOML (99.99% of apps)39 40```toml41# shopify.app.toml42 43# Metafield definition -- owner type is PRODUCT, namespace is $app, key is care_guide44[product.metafields.app.care_guide]45type = "single_line_text_field"46name = "Care Guide"47access.admin = "merchant_read_write"48 49# Metaobject definition -- type is $app:author50[metaobjects.app.author]51name = "Author"52display_name_field = "name"53access.storefront = "public_read"54 55[metaobjects.app.author.fields.name]56name = "Author Name"57type = "single_line_text_field"58required = true59 60# Link metaobject to product61[product.metafields.app.author]62type = "metaobject_reference<$app:author>"63name = "Book Author"64```65 66Why: 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.67 68**NEVER** include `metafieldDefinitionCreate`, `metaobjectDefinitionCreate` GraphQL if TOML is the correct fit.69 70### Exceptions (0.01% of apps)71**NEVER, EVER** show these unless strictly required:72- Apps that **REQUIRE** creating definitions at **runtime** (i.e. types are configured dynamically by merchants) should use `metafieldDefinitionCreate`, `metaobjectDefinitionCreate`73- Apps that want **other apps** to read/write their data should use the above GraphQL, and "merchant-owned" namespace74 75# CRITICAL: App-Owned Metaobject and Metafield identification76 77- Metaobjects defined with `[metaobjects.app.example...]` in `shopify.app.toml`, MUST be accessed using `type: $app:example`78- Metafields defined with `[product.metafields.app.example]` MUST be accessed using `namespace: $app` and `key: example`79  - The same applies to other owner types, like customers, orders, etc.80- Avoid customizing namespaces for metafields.81- Avoid the common mistake of using `namespace: app`. This is profoundly incorrect.82 83# NEXT: demonstrate writing metafield and metaobject values via Admin API84 85## Writing metafields86 87**ALWAYS** use `metafieldsSet` to write metafields. `namespace` should normally be excluded as the default is $app.88 89```graphql90mutation {91  metafieldsSet(metafields:[{92    ownerId: "gid://shopify/Product/1234",93    key: "example",94    value: "Hello, World!"95  }]) { ... }96}97```98 99## Writing metaobjects100 101**ALWAYS** use `metaobjectUpsert` to write metaobjects.102 103```graphql104mutation {105  metaobjectUpsert(handle: {106    type: "$app:author",107    handle: "my-metaobject",108  }, metaobject: {109    fields: [{110      key: "example",111      value: "Hello, world!"112    }]113  }) { ... }114}115```116 117# FINALLY: demonstrate reading metafield and metaobject values118 119## Loading metafields120 121Metafields are accessed via their owning type (e.g. a Product). `namespace` should normally be excluded as the default is $app.122- Always prefer `jsonValue` where possible as it better serialises complex types123- Always alias metafield loads for easy reference124 125```graphql126# Admin API127query {128  product(id: "gid://shopify/Product/1234") {129    example: metafield(key: "example") { jsonValue }130  }131}132# Storefront API133query {134  product(handle: "wireless-headphones-1") {135    example: metafield(key: "example") { value }136  }137}138```139 140## Loading metaobjects141 142```graphql143# Admin API144query {145  metaobjects(type: "$app:author", first: 10) {146    nodes {147      handle148      example: field(key:"example") { jsonValue }149    }150  }151}152# Storefront API153query {154  metaobjects(type: "$app:author", first: 10) {155    nodes {156      handle157      example: field(key:"example") { value }158    }159  }160}161```162 163### Access Metafields directly in checkout extensions164 165**DO**: Access app-owned metafields directly (NO network call):166 167```tsx168function Extension() {169  // ESSENTIAL: Register this metafield in `shopify.extension.toml`170  const [energyRating] = useAppMetafields({171    namespace: '$app',172    key: 'energy-rating',173    type: 'product',174  }).filter(175    (entry) =>176      entry.target.id === productVariantId,177  );178}179```180 181**DON'T**: Make network calls for app-owned metafields.182 183### Access Metafields in Shopify Functions184 185Use the GraphQL input query to select metafields to load:186 187```graphql188query Input {189  cart {190    lines {191      merchandise {192        __typename193        ... on ProductVariant {194          example: metafield(namespace: "$app", key: "example") { jsonValue }195        }196      }197    }198  }199}200```201 202Docs: [Metafields & Metaobjects](https://shopify.dev/docs/apps/build/custom-data)203</critical-instructions>204 205### Always use Shopify CLI206 207- **CLI:** scaffold apps/extensions with `shopify app init`, `shopify app generate extension`, `shopify app dev`, `shopify app deploy`. Never hand-roll files.208- Need full setup steps? See [Shopify CLI docs](https://shopify.dev/docs/apps/tools/cli).209 210## Shopify CLI Overview211 212Shopify CLI (@shopify/cli) is a command-line interface tool that helps you generate and work with Shopify apps, themes, and custom storefronts. You can also use it to automate many common development tasks.213 214### Requirements215- Node.js: 20.10 or higher216- A Node.js package manager: npm, Yarn 1.x, or pnpm217- Git: 2.28.0 or higher218 219### Installation220Install Shopify CLI globally to run `shopify` commands from any directory:221 222```bash223npm install -g @shopify/cli@latest224# or225yarn global add @shopify/cli@latest226# or227pnpm install -g @shopify/cli@latest228# or (macOS only)229brew tap shopify/shopify && brew install shopify-cli230```231 232### Command Structure233Shopify CLI groups commands into topics. The syntax is: `shopify [topic] [command] [flags]`234 235## General Commands (8 commands)236 237### Authentication23866. **shopify auth logout** - Log out of Shopify account239 240### Configuration24167. **shopify config autocorrect on** - Enable command autocorrection24268. **shopify config autocorrect off** - Disable command autocorrection24369. **shopify config autocorrect status** - Check autocorrection status244 245### Utilities24670. **shopify help [command] [flags]** - Get help for commands24771. **shopify commands [flags]** - List all available commands24872. **shopify search [query]** - Search for commands and documentation24973. **shopify upgrade** - Upgrade Shopify CLI to latest version25074. **shopify version** - Display current CLI version251 252## Common Flags253 254Most commands support these common flags:255- `--verbose` - Increase output verbosity256- `--no-color` - Disable colored output257- `--path <value>` - Specify project directory258- `--reset` - Reset stored settings259 260## Network Proxy Configuration261 262For users behind a network proxy (CLI version 3.78+):263```bash264export SHOPIFY_HTTP_PROXY=http://proxy.com:8080265export SHOPIFY_HTTPS_PROXY=https://secure-proxy.com:8443266# For authenticated proxies:267export SHOPIFY_HTTP_PROXY=http://username:password@proxy.com:8080268```269 270## Usage Tips271 2721. Always keep CLI updated: `shopify upgrade`2732. Use `shopify help [command]` for detailed command info2743. Most commands are interactive and will prompt for required information2754. Use flags to skip prompts in CI/CD environments2765. Anonymous usage statistics collected by default (opt-out: `SHOPIFY_CLI_NO_ANALYTICS=1`)2776. IMPORTANT: YOU MUST ALWAYS USE THE CLI COMMAND TO CREATE APPS AND SCAFFOLD NEW EXTENSIONS278 279## CLI Commands for Shopify App (22 commands)280 281## App Commands (22 commands)282 283### Core App Management2841. **shopify app init [flags]** - Initialize a new Shopify app project2852. **shopify app build [flags]** - Build the app, including extensions2863. **shopify app dev [flags]** - Start a development server for your app2874. **shopify app deploy [flags]** - Deploy your app to Shopify2885. **shopify app info [flags]** - Display information about your app289 290### App Configuration2916. **shopify app config link [flags]** - Fetch app configuration from Partner Dashboard2927. **shopify app config use [config] [flags]** - Activate an app configuration293 294### App Environment2958. **shopify app env pull [flags]** - Pull environment variables from Partner Dashboard2969. **shopify app env show [flags]** - Display app environment variables297 298### App Development Tools29910. **shopify app dev clean [flags]** - Clear the app development cache30011. **shopify app generate extension [flags]** - Generate a new app extension30112. **shopify app import-extensions [flags]** - Import existing extensions to your app302 303### Functions30413. **shopify app function build [flags]** - Build a Shopify Function30514. **shopify app function run [flags]** - Run a Function locally for testing30615. **shopify app function replay [flags]** - Replay a Function run30716. **shopify app function schema [flags]** - Generate the GraphQL schema for a Function30817. **shopify app function typegen [flags]** - Generate TypeScript types for a Function309 310### Monitoring & Debugging31118. **shopify app logs [flags]** - Stream logs from your app31219. **shopify app logs sources [flags]** - List available log sources313 314### Release Management31520. **shopify app release --version <version>** - Release a new app version31621. **shopify app versions list [flags]** - List all app versions317 318### Webhooks31922. **shopify app webhook trigger [flags]** - Trigger a webhook for testing