---
title: >-
  Metafields now require a definition to be accessed through the Customer
  Account API - Shopify developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/metafields-now-require-a-definition-to-be-accessed-through-the-customer-account-api
  md: >-
    https://shopify.dev/changelog/metafields-now-require-a-definition-to-be-accessed-through-the-customer-account-api.md
metadata:
  effectiveApiVersion: ''
  affectedApi: []
  primaryTag:
    displayName: Platform
    handle: platform
  secondaryTag:
    displayName: Update
    handle: update
  indicatesActionRequired: true
  createdAt: '2026-06-15T15:51:27-04:00'
  postedAt: '2026-06-16T12:00:00-04:00'
  updatedAt: '2026-06-16T17:51:13-04:00'
  effectiveAt: '2026-06-16T12:00:00-04:00'
---

June 16, 2026

Tags:

* Action Required
* Platform

# Metafields now require a definition to be accessed through the Customer Account API

Starting today, metafields stored on the app resource must have a metafield [definition](https://shopify.dev/docs/apps/build/metafields#metafield-definitions) and customer accounts [permissions](https://shopify.dev/docs/apps/build/metafields#customer-accounts-permissions) to be accessible through the Customer Account API. Going forward, when calling the Customer Accounts API, app metafields without a definition will no longer return a value. If your app has functionality which depends on these fields, update those metafields to use definitions with the Customer Account API permission to avoid disruption.

## Action required:

You must ensure that every metafield your app uses for customer account UI extensions, a Hydrogen or a Headless store, has a definition.

* Run the [metafieldDefinitionCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionCreate) for every store that installs your app to ensure the metafields are correctly defined.
* For app-owned metafields, configure [declarative metafields](https://shopify.dev/docs/apps/build/metafields/definitions#toml-app-owned-example) in your app’s TOML file.
* Configure the [access settings](https://shopify.dev/docs/apps/build/metafields#customer-accounts-permissions) on your definition to allow customer accounts API access.

*Metafields owned by Customer or Order resources will not be affected by this change.*