Building metafield writes into extensions

Writing to metafields directly from the Customer Account API enables you to store additional information about customers within Shopify, without making a separate call to the GraphQL Admin API, a third-party server, or other external resource.

In this tutorial, you'll create a customer account UI extension for the Profile page, to enable a merchant to collect a customer’s preferred nickname and pass that input into a metafield.

Anchor to LimitationsLimitations

Metafield writes are only supported on the Customer, Order, Company, and CompanyLocation objects. Metafield writes are available as of the 2024-07 version of the Customer Account API.

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

Use TOML declarative custom data definitions to configure a metafield definition with permissions to read and write to metafields using the Customer Account API.
Create an extension that's rendered on the customer account Profile page.
Use the Customer Account API to write data to a metafield.

Requirements

Create a Partner account

Create a development store

The development store should be pre-populated with test data, including an order associated with the email address you'll use to log in to the customer account experience.

Shopify CLI

You'll need to use the latest version of Shopify CLI.

Scaffold an app

Scaffold an app that uses Shopify CLI.

Request access to Protected Customer Data

The Customer Account API requires access to Level 1 Protected Customer Data. Request access for your app.

Project

View on GitHub

Anchor to Create a customer account UI extensionCreate a customer account UI extension

To create a customer account UI extension, you can use Shopify CLI, which generates starter code for building your extension and automates common development tasks.

Navigate to your app directory:

Terminal
cd <directory>
Run the following command to create a new customer account UI extension:

Terminal
shopify app generate extension --template customer_account_ui --name customer-account-ui-extension

You should now have a new extension directory in your app's directory. The extension directory includes the extension script at src/{FileName}.jsx. The following is an example directory structure:

Customer account UI extension file structure
└── my-app
└── extensions
└── my-customer-account-ui-extension
├── src
│ └── CustomerAccount.jsx // The index page of the customer account UI extension
├── locales
│ ├── en.default.json // The default locale for the customer account UI extension
│ └── fr.json // The locale file for non-regional French translations
├── shopify.extension.toml // The config file for the customer account UI extension
└── package.json

Start your development server to build and preview your app:

Terminal
shopify app dev

To learn about the processes that are executed when you run dev, refer to the Shopify CLI command reference.
Press p to open the developer console. In the developer console page, click on the preview link for your extension.

Anchor to Configure access scopes for your appConfigure access scopes for your app

To read or write metafield data on the CUSTOMER resource using the Customer Account API, you'll need to include the customer_read_customers and customer_write_customers access scopes in your app's shopify.app.toml file.

Anchor to Create the metafield definitionCreate the metafield definition

Use a declarative custom data definition to configure metafield definitions directly in your app's configuration file.

In your app's shopify.app.toml file, add a [customer.metafields.app.nickname] section to define the metafield:

This creates a metafield to store customer nickname preferences, allowing customers to personalize their account information through your extension.

Anchor to Set up the targets for your extensionSet up the targets for your extension

Set up the targets for your customer account UI extension. Extension targets control where your extension renders in the customer account flow.

You'll use a block extension target to render a card on the Profile page and to render a modal when the button is clicked.

Anchor to Reference the extension targets in your configuration fileReference the extension targets in your configuration file

This example code uses the customer-account.profile.block.render extension target.

In your extension's shopify.extension.toml configuration file, create an [[extensions.targeting]] section with the target, an identifier that specifies where you're injecting code into Shopify, and module, the path to the file that contains the extension code.

Anchor to Create files for your targetsCreate files for your targets

Create files in your extension's src directory for each of your targets.

In this example, you'll create a file for the Profile page extension. The filenames must match the module paths you specified.

Anchor to Build the customer account UI extension for the ,[object Object], pageBuild the customer account UI extension for the Profile page

Use Polaris web components to build the UI of your extension.

In this example, a new s-section component is added to the Profile page. The section displays the current nickname. An s-link component is rendered that opens an s-modal component where a customer can update their nickname. The modal contains an s-text-field component where the user can input their new nickname.

/preact/example-customer-account--metafields--preact/extensions/customer-preferences/src/ProfilePreferenceExtension.jsx

// @ts-nocheck

import {render} from 'preact';

import {useState, useRef} from 'preact/hooks';

export default async () => {

const {customerId, nickName} = await getCustomerPreferences();

render(

<ProfilePreferenceExtension customerId={customerId} nickName={nickName} />,

document.body

);

};

function ProfilePreferenceExtension(props) {

const {i18n} = shopify;

const modalRef = useRef();

const [loading, setLoading] = useState(false);

const [nickName, setNickName] = useState(props.nickName ?? '');

const [newNickName, setNewNickName] = useState(nickName);

const handleSubmit = async (e) => {

e.preventDefault();

setLoading(true);

const updatedNickname = await setCustomerPreferences(

props.customerId,

newNickName

);

setNickName(updatedNickname);

setLoading(false);

modalRef.current?.hideOverlay();

};

const handleCancel = () => {

modalRef.current?.hideOverlay();

};

Fetch the customer's nickname metafield value by querying the Customer Account API. Display the returned nickname value in the card.

/preact/example-customer-account--metafields--preact/extensions/customer-preferences/src/ProfilePreferenceExtension.jsx

// @ts-nocheck

import {render} from 'preact';

import {useState, useRef} from 'preact/hooks';

export default async () => {

const {customerId, nickName} = await getCustomerPreferences();

render(

<ProfilePreferenceExtension customerId={customerId} nickName={nickName} />,

document.body

);

};

function ProfilePreferenceExtension(props) {

const {i18n} = shopify;

const modalRef = useRef();

const [loading, setLoading] = useState(false);

const [nickName, setNickName] = useState(props.nickName ?? '');

const [newNickName, setNewNickName] = useState(nickName);

const handleSubmit = async (e) => {

e.preventDefault();

setLoading(true);

const updatedNickname = await setCustomerPreferences(

props.customerId,

newNickName

);

setNickName(updatedNickname);

setLoading(false);

modalRef.current?.hideOverlay();

};

const handleCancel = () => {

modalRef.current?.hideOverlay();

};

Localization can be used to translate the UI of your extension into multiple languages. In this example, English is the default locale by including en.default.json in the locales.

In our example, French is also supported by providing an fr.json file in the locales directory.

Anchor to Write the user input to your metafieldWrite the user input to your metafield

Make a request to the metafieldsSet mutation to write the user input to the metafield.

Pass the previously defined key and namespace to the metafieldsSet mutation to identify the metafield you want to update. The ownerId is the ID of the object whose metafield you want to update. In this example, it is the ID of the current customer. In this case, the value is the new nickname that the customer has inputted.

/preact/example-customer-account--metafields--preact/extensions/customer-preferences/src/ProfilePreferenceExtension.jsx

// @ts-nocheck

import {render} from 'preact';

import {useState, useRef} from 'preact/hooks';

export default async () => {

const {customerId, nickName} = await getCustomerPreferences();

render(

<ProfilePreferenceExtension customerId={customerId} nickName={nickName} />,

document.body

);

};

function ProfilePreferenceExtension(props) {

const {i18n} = shopify;

const modalRef = useRef();

const [loading, setLoading] = useState(false);

const [nickName, setNickName] = useState(props.nickName ?? '');

const [newNickName, setNewNickName] = useState(nickName);

const handleSubmit = async (e) => {

e.preventDefault();

setLoading(true);

const updatedNickname = await setCustomerPreferences(

props.customerId,

newNickName

);

setNickName(updatedNickname);

setLoading(false);

modalRef.current?.hideOverlay();

};

const handleCancel = () => {

modalRef.current?.hideOverlay();

};

Anchor to Preview the extensionPreview the extension

Use the Shopify CLI to preview your extension to make sure that it works as expected.

In a terminal, navigate to your app directory.
Start app dev if you haven't already to build and preview your app:

shopify app dev
If prompted, select a dev store.
Once started, press p or navigate to the preview link in the developer console.
In the developer console page, click the preview link for your extension target.
Click the edit icon in the Preferences card to open the modal and update the nickname metafield value.

Troubleshooting

Anchor to Extension not renderingExtension not rendering

Ensure that your app is installed on the dev store you're testing with.

Check your browser's developer console for any errors that might be preventing the extension from rendering.

Anchor to Metafield not updatingMetafield not updating

If the metafield value isn't being properly persisted, for example if the value that you specified isn't being saved after a page reload, do the following:

Ensure that the namespace and key used to create the metafield definition match the values being used in the metafieldsSet mutation.
Check your network traffic for the response to the metafieldsSet mutation. The response will contain a userErrors field that will provide more information about what went wrong.

Anchor to Deploy your extensionDeploy your extension

When you're ready to release your changes to users, you can create and release an app version. An app version is a snapshot of your app configuration and all extensions.

Navigate to your app directory.
Run the following command.

Optionally, you can provide a name or message for the version using the --version and --message flags.

Terminal
shopify app deploy

Releasing an app version replaces the current active version that's served to stores that have your app installed. It might take several minutes for app users to be upgraded to the new version.

Tip

If you want to create a version, but avoid releasing it to users, then run the deploy command with a --no-release flag. You can release the unreleased app version using Shopify CLI's release command, or through the Dev Dashboard.

/preact/example-customer-account--metafields--preact/shopify.app.toml

name = "ca-metafields"

application_url = "https://shopify.dev/apps/default-app-home"

embedded = true

[build]

automatically_update_urls_on_dev = true

include_config_on_deploy = true

[webhooks]

api_version = "2025-10"

[access_scopes]

scopes = "write_customers, customer_write_customers"

[auth]

redirect_urls = [ "https://shopify.dev/apps/default-app-home/api/auth" ]

[customer.metafields.app.nickname]

type = "single_line_text_field"

name = "The customer's preferred name"

description = "The customer's preferred nickname for personalization"

access.customer_account = "read_write"

access.admin = "merchant_read"

/preact/example-customer-account--metafields--preact/extensions/customer-preferences/shopify.extension.toml

api_version = "2025-10"

[[extensions]]

name = "customer-preferences"

handle = "customer-preferences"

uid = "e0260bd4-f328-fedf-994f-bfeb7e42f14a9089f017"

type = "ui_extension"

[[extensions.targeting]]

module = "./src/ProfilePreferenceExtension.jsx"

target = "customer-account.profile.block.render"

/preact/example-customer-account--metafields--preact/extensions/customer-preferences/src/ProfilePreferenceExtension.jsx

// @ts-nocheck

import {render} from 'preact';

import {useState, useRef} from 'preact/hooks';

export default async () => {

const {customerId, nickName} = await getCustomerPreferences();

render(

<ProfilePreferenceExtension customerId={customerId} nickName={nickName} />,

document.body

);

};

function ProfilePreferenceExtension(props) {

const {i18n} = shopify;

const modalRef = useRef();

const [loading, setLoading] = useState(false);

const [nickName, setNickName] = useState(props.nickName ?? '');

const [newNickName, setNewNickName] = useState(nickName);

const handleSubmit = async (e) => {

e.preventDefault();

setLoading(true);

const updatedNickname = await setCustomerPreferences(

props.customerId,

newNickName

);

setNickName(updatedNickname);

setLoading(false);

modalRef.current?.hideOverlay();

};

const handleCancel = () => {

modalRef.current?.hideOverlay();

};

/preact/example-customer-account--metafields--preact/extensions/customer-preferences/locales/en.default.json

{

"preferenceCard": {

"heading": "Preferences",

"nickName": {

"label": "Nickname"

"edit": "Edit",

"modalHeading": "Edit preferences",

"save": "Save",

"cancel": "Cancel"

}

/preact/example-customer-account--metafields--preact/extensions/customer-preferences/locales/fr.json

{

"preferenceCard": {

"heading": "Préférences",

"nickName": {

"label": "Surnom"

"edit": "Modifier",

"modalHeading": "Modifier les préférences",

"save": "Sauvegarder",

"cancel": "Annuler"

}

Anchor to Tutorial complete!Tutorial complete!

Nice work - what you just built could be used by Shopify merchants around the world! Keep the momentum going with these related tutorials and resources.

Anchor to Next StepsNext Steps

Working with metafields

Explore methods for adding and storing custom data about a Shopify resource with metafields.

Extension placement

Explore extension placement options and make informed decisions on where to position them.

Localize your extension

Learn about localizing your customer account UI extensions for international merchants and customers.

Extension targets

Learn about the extension targets offered in customer account.

Polaris web components

Learn about the components you can use to build customer account UI extensions.

UX guidelines

Follow our UX guidelines for customer accounts to ensure a consistent and satisfying user experience.

Figma UI kit

Explore Figma components for checkout and account UI extensions.

Was this page helpful?