Metafields

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 app’s modern metafield 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 using the key as the unique identifier. Metafields are stored with the following structure:

Namespace

customer_fields (default)

Update
We now allow you to control the metafield namespace when creating new data columns. You can edit the app’s default namespace to use something other than customer_fields for all new columns, and/or define your own custom namespaces individually for each new column.

Key

A data column’s key

Type

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

Note
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. The examples below use the customer_fields namespace:

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 {
          id
          key
          value
        }
      }
    }
  }
}

Metafield definitions

Using a metafield definition allows you to display and edit custom values directly from the Shopify Admin UI. 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.

Warning
You must exactly match the data column’s type with the metafield type in Shopify. 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. The same is also true for namespaces; the data column namespace needs to match the intended metafield namespace in Shopify.

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
{{ customer.metafields.customer_fields.data["my_custom_field"] }}

# Updated
{{ customer.metafields.customer_fields.my_custom_field.value | default: customer.metafields.customer_fields.data["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.

Note
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