Merchants: Let Customers Edit Shopify Customer Metafields, GDPR

Shopify customer metafields are typed custom fields attached to a customer record, letting you store structured data beyond the default profile. They cover two main jobs: personalization, like saving a nickname or communication preference, and automation, like tagging customers by loyalty tier for segmentation. Metafield definitions and Shopify’s APIs control exactly how each field behaves.

TL;DR:

• Customer metafields should be defined with the appropriate data type and ownership to ensure proper validation, visibility, and editability.
• Using metafieldsSet with the compareDigest parameter prevents conflicting updates when multiple systems modify the same field.
• Shopify’s Customer Account API enables customers to update their own metafields directly from the account page, provided the app has the necessary protected scopes.
• Structuring data with metafields offers a scalable alternative to tags, especially for validated values like loyalty tiers or membership IDs.
• Best practices include testing metafield logic on staging stores, maintaining consistent naming conventions, and limiting data access scopes to protect sensitive customer information.

Table of Contents

• What customer metafields are and where merchants use them
• Ownership and visibility: merchant-owned, app-owned, and app-data
• How to create metafield definitions and choose data types
• Reading and writing customer metafields: Admin API and Customer Account API
• How Shopify Flow uses customer metafields for automation
• Best practices for security, concurrency, and testing
• Step-by-step: creating, reading, and writing a customer metafield
• How we apply customer metafields at AccountCraft
• Build editable customer account fields without writing code
• FAQ
• Sources

What customer metafields are and where merchants use them

A customer metafield is a typed custom field, backed by a definition that specifies whether it holds a single line of text, a number, a list, or another supported type. Shopify’s metafield definitions documentation describes them as custom fields that store additional structured data for customers, governed by schemas that enforce consistency across your store and apps.

Common merchant uses include:

• Loyalty tier labels that drive discount logic or email segments.
• Birthdates used to trigger automated offers.
• Communication preferences, such as preferred language or contact channel.
• Membership or subscription IDs linked to external systems.
• Wishlist items saved for later purchase.

Metafields beat tags when you need structured, validated values rather than a flat label. A tag works for a quick “VIP” flag, but a metafield definition keeps a loyalty tier restricted to approved values and queryable as actual data, not just a string.

Ownership and visibility: merchant-owned, app-owned, and app-data

Who controls a metafield determines where it appears and who can edit it. Shopify’s metafields overview splits ownership into three models:

• Merchant-owned metafields: editable from the Shopify admin and shareable across apps that request access.
• App-owned metafields: managed by a specific app, often hidden from the admin interface.
• App-data metafields: tied to a single app installation and hidden from both the admin and other apps.

Pick merchant-owned fields when store staff or multiple apps need to see and edit a value, such as a loyalty tier. Reserve app-owned or app-data fields for internal logic that customers and staff never touch directly, and plan any ownership change carefully since it affects both visibility and editability going forward.

How to create metafield definitions and choose data types

Creating a definition before writing any values gives you schema validation and a consistent admin UI, instead of loose, unvalidated data scattered across customer records — learn more about structured data SEO with rich results.

1. Decide where to define the field: the Shopify Admin UI for quick setup, the GraphQL Admin API for programmatic control, or a TOML configuration inside an app for packaged distribution.
2. Choose a namespace and key that describe the field’s purpose and app ownership clearly.
3. Match the data type to the content: a loyalty tier works well as single_line_text_field, a join date as date, a point balance as number_integer, and a list of favorite categories as a list.single_line_text_field.
4. Save the definition, then confirm it appears correctly in the admin or your app’s metafield list before writing values.

Getting the type right the first time avoids rework later, since changing a field’s type after values exist often means a migration.

Reading and writing customer metafields: Admin API and Customer Account API

The GraphQL Admin API lets you query a specific field with customer.metafield(namespace, key) or fetch several at once, then write values with the metafieldsSet mutation. According to the metafieldsSet mutation reference, this mutation is atomic, accepts up to 25 metafields per call, and supports compare-and-set behavior through compareDigest to prevent conflicting writes.

A key capability for 2026 storefronts: the Customer Account API’s metafield support allows UI extensions to write customer metafields directly from the front end once an app has the protected scopes customer_read_customers and customer_write_customers. This means a customer can update their own preferences or saved details without a round trip through a custom backend.

Key mechanics worth remembering:

• metafieldsSet processes writes atomically, so a batch either fully succeeds or reports errors.
• compareDigest compares the current stored value before writing, which blocks a second writer from silently overwriting a concurrent change.
• Protected scopes are required before any customer-facing extension can write data, and Shopify reviews that access during app approval.

How Shopify Flow uses customer metafields for automation

Shopify Flow treats a metafield as a workflow variable, which opens up automations that would otherwise need custom code. Shopify’s Flow metafields documentation explains how this works in practice.

1. When adding a variable to a Flow trigger or action, select metafield (singular), not metafields, since the plural option refers to the full collection rather than one value.
2. Build a scheduled workflow that reads a metafield like loyalty tier and copies its value into a customer tag, keeping your segments current without manual tagging.
3. Chain a condition step so the backfill only applies to customers whose metafield value changed since the last run, which keeps the automation efficient.

Some templates, including certain scheduled backfills, require Shopify Plus or a third-party automation app to unlock the trigger types involved.

Best practices for security, concurrency, and testing

Treat customer metafield data as sensitive by default, and request only the scopes your app genuinely needs. The Customer Account API documentation recommends minimizing protected customer data access and keeping heavy business logic on the server rather than inside a front-end extension, which simplifies debugging and reduces exposure.

When multiple systems might write to the same field, such as an app, a Flow automation, and a manual admin edit, use compareDigest in your metafieldsSet calls to implement compare-and-swap behavior. This stops one writer from overwriting another’s change without warning.

A few additional habits prevent avoidable problems:

• Adopt consistent namespace and key naming conventions early, and document any migration plan before changing a field’s type or ownership.
• Always check the userErrors array returned by metafieldsSet and log failures for debugging.
• Test new metafield logic on a staging store before pushing it to production.

Pro Tip: Log every metafieldsSet response during development, even successful ones, so you can trace exactly when and why a value changed later.

Step-by-step: creating, reading, and writing a customer metafield

A typical implementation follows a short, repeatable sequence from schema to working write access.

1. Create the metafield definition in the Admin UI or via the GraphQL Admin API, specifying namespace, key, and type.
2. Update your app’s shopify.app.toml to request the scopes needed for read and write access, then submit for protected customer data approval if the field touches personal information.
3. Implement a read query using customer.metafield(namespace, key) to confirm the value appears as expected.
4. Implement a write using metafieldsSet, passing the customer’s ownerId, the namespace, key, type, and new value.

A minimal metafieldsSet call needs four things: the customer’s ownerId, the metafield’s namespace and key, and the type matching its definition, plus the value you want stored.

For a front-end write, a Customer Account UI extension calls the same mutation through the shopify:customer-account API, letting a logged-in customer update their own saved preference directly from their account page.

How we apply customer metafields at AccountCraft

We built AccountCraft around the same metafield patterns covered above: editable customer fields rendered through a visual block builder, with no theme code to maintain. Each field a merchant adds, whether a loyalty tier, a saved preference, or a repeatable list like vehicles or pets, maps to a metafield definition under the hood, so the data stays structured and stays in Shopify.

Consent management is linked to Shopify’s own consent APIs, which keeps GDPR-related preferences editable by the customer.

— Barikreativa

Build editable customer account fields without writing code

We created AccountCraft so merchants could turn the metafield patterns in this guide into working account pages without touching a theme file or hiring a developer. The Block Builder lets you add editable fields, wishlists, and repeatable lists directly to the New Customer Accounts experience, while data stays inside Shopify and consent stays tied to Shopify’s own APIs.

• Add editable fields like loyalty tier or birthday in minutes, not sprints.
• Keep GDPR-related consent management built into the same account page.
• Choose from Free, Pro, and Plus plans depending on how much customization you need.

Check current plan details and get started at AccountCraft.

FAQ

What is Shopify metafields?

Metafields are typed custom fields that store extra structured data on Shopify resources like customers, products, and orders, governed by a definition that sets the data type and validation rules. For customers specifically, they commonly hold loyalty tiers, preferences, and membership details, as described in Shopify’s metafield definitions documentation.

What is the difference between metafields and tags in Shopify?

Tags are simple text labels with no enforced structure, useful for quick filtering or segmentation. Metafields are typed and validated through a definition, which makes them better suited to data that needs a consistent format, like a date or a number, rather than a loose label.

What are the different types of metafields in Shopify?

Metafields support types including single line text, multi-line text, number (integer or decimal), date, boolean, and list variants of these, each enforced by the field’s definition. Shopify’s metafields overview also distinguishes metafields by ownership: merchant-owned, app-owned, and app-data.

What are category metafields in Shopify?

Category metafields are standardized metafields tied to Shopify’s product taxonomy, used mainly to describe product attributes consistently across a category rather than customer data. For customer-specific use cases like loyalty or preferences, you typically define your own custom metafields instead, as outlined in the metafield definitions guide.

Can customers edit their own metafields through their account page?

Yes, once an app requests the protected scopes customer_read_customers and customer_write_customers, a Customer Account UI extension can let customers view and update their own metafield values directly, according to Shopify’s Customer Account API documentation. We use this same capability to render editable fields on customer account pages without custom code.

Sources

• Metafield definitions — Shopify developer docs
• Metafields in Shopify Flow — Shopify Help Center