Link Search Menu Expand Document


We store custom data on customers in both the app and in Shopify’s metafields. This allows you as a developer to access this data either through the Shopify API or your theme’s Liquid. If you haven’t already, learn about how metafields work in Shopify by reviewing their documentation.

The default metafields strategy is to store each custom value as its own metafield within Shopify. We’ll only store a metafield that has a corresponding data column within the app. Metafields are stored with the following structure:




A data column’s key


A data column’s metafield type. Reference the following map of data column type to metafield type:

Data column type
(Customer Fields)
Metafield type
single_line_text single_line_text_field
text multi_line_text_field
email single_line_text_field
phone single_line_text_field
list list.single_line_text_field
date date
date_time date_time
integer number_integer
float number_decimal
file json
boolean boolean
group json
group_list json

Child data columns (as determined by a key with a separating period, e.g. ‘parent.child’) are never stored as a top level metafield. These values get stored within a group or group_list JSON object as sub-property values.

Reading from metafields

You can access customer metafields like any other resource:

Liquid example

{{ customer.metafields.customer_fields.favorite_color.value }}

GraphQL example

query {
  customer (id: "gid://shopify/Customer/582914830492") {
    custom_data: metafields (first: 10, namespace: "customer_fields") {
      edges {
        node {

Metafield definitions

Using a metafield definition allows you to show and edit custom values directly from the Shopify admin. Definitions can be pinned so they show directly on the customer admin page. Customer Fields will automatically attempt to create metafield definitions for each data column.

You must exactly match the data column’s type with the metafield type. Failing to do so will result in errors. See the above table for data column types to metafield type references. For example, a definition matching a data column (by namespace/key) with type integer must use the number_integer type.

Writing to metafields

In addition to using metafield definitions, you can write custom data into the app via our REST API or by modifying metafields via the Shopify API.

In order to write custom data via a metafield, two-way metafields syncing must be enabled, which can be found under the Advanced settings within the app. Only metafields with a namespace and key that correlate to a data column will be saved. The change normally processes within 10-15 seconds, but in certain cases it may take longer.

Be sure to provide a value that can be coerced into the data column’s type. All metafield values saved to Shopify are strings, but are parsed into their corresponding data type within the app. For example if you update a metafield that matches a data column with type boolean with a value of "true" or "Yes", we’ll consume the value as true.

Subscribe to changes with webhooks

As customer data is updated, you can subscribe to Shopify webhooks to keep data in sync. If you’re subscribing to Shopify webhooks, you can include the metafield_namespaces: "customer_fields" parameter to receive our custom data within each request. You’ll be sent a webhook even when only the metafield changed.

We also offer direct webhook subscriptions in addition to Shopify via our REST API.

Bundled JSON metafield strategy

Prior to April 2022, we stored metafields under a single metafield with type json_string. Since Shopify released metafield definitions, we’ve changed the default way metafields are stored to be compatible with new metafields types.

You can set your strategy within Customer Fields > Settings > Metafields. With this strategy, you can access all custom data within a single metafield with namespace customer_fields and key data.

Migrating to support metafield definitions

We recommend all shops migrating to the new metafield strategy. We’ve built a data migrator which handles saving custom data into individual metafields. This migration happens when you switch from bundled metafield strategy to the Shopify admin-compatible strategy.

In order to prepare for the migration, you’ll want to consider where you’re referencing the old data metafield. Depending on the amount of customers within your shop, this migrating can take some time to process and you’ll want to prepare handling both uses cases while the migration is running. Any new customers that register while the migration is running will use the new strategy.

Update Liquid references

If you’re referencing a metafield in Liquid, first look up the single metafield and then fallback to the bundled metafield value. Example:

# Original
{{["my_custom_field"] }}

# Updated
{{ customer.metafields.customer_fields.my_custom_field.value | default:["my_custom_field"] }}

Update API references

If you’re using the Shopify API to access custom data, use the same strategy of checking first for the individual metafield by the data column’s key and then fallback on the JSON object under the data key.

Psuedo Ruby code:

birthday_metafield = customer.metafields.find {|m| m.key == "birthday" }
data_metafield = customer.metafields.find {|m| m.key == "data" } || {}

birthday = birthday_metafield || data_metafield["birthday"]

After the migration completes, do a spot check on your data to ensure all your custom data on customers has been migrated properly. At this point you may choose to update any custom code to only read from the newly created metafields and ignore the data metafield.

We used to store metafields under the namespace customr when using the legacy fields editor. If you’re using the legacy fields editor, we recommend you migrate your fields and switch to Shopify-admin compatible metafields.

Next up: Customer API

Have any questions or comments about this post? Let us know! Your feedback is greatly appreciated.

Customer Fields is a Shopify app made by Helium.

Copyright © Helium Development, LLC