Link Search Menu Expand Document

Metafields

We store customer data 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 Liquid. If you haven’t already, learn about how metafields work in Shopify by reviewing their documentation.

Read custom data in Liquid

All of a customer’s custom data is stored in a single JSON metafield: customer.metafields.customer_fields.data. Here’s how you can access the column my_column_key:

{{ customer.metafields.customer_fields.data["my_column_key"] }}

or:

{{ customer.metafields.customer_fields.data.my_column_key }}

This can be used anywhere on a theme. However, that’s a very elongated path to the data you want. We recommend assigning a variable to customer.metafields.customer_fields.data so you don’t have to keep repeating it:

{% assign custom_data = customer.metafields.customer_fields.data %}

{{ custom_data["some_column"] }}
{{ custom_data["some_other_column"] }}

Read custom data from Shopify API

You can access custom data through Shopify’s API. You may fetch our metafield by looking it up with our namespace and key. If you’re using GraphQL, you can do this in one request.

Example GraphQL request:

{
  customer(id: "gid://shopify/Customer/2683687567407") {
    firstName
    lastName
    email
    custom_data: metafield(namespace: "customer_fields", key: "data") {
      value
    }
  }
}

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.

Write custom data from Shopify API

You can write custom data into the app via our REST API or by modifying our metafield via the Shopify API.

In order to write custom data via a metafield, you must first enable two-way metafield syncing within the app. Under the Settings tab within Customer Fields, visit the Advanced settings and enable two-way syncing. If you do not enable this setting, any changes within Customer Fields will overwrite your changes.

With two-way syncing enabled, you can now make updates via the Shopify API to the metafield and we’ll pick up the changes and update the customer on our end. In general this can take up to 15 seconds after the update. If you create a new customer with a metafield, ensure you’ve namespaced the metafield with customer_fields, a key of data, and value type of json_string. You must provide a valid JSON object to this metafield or two-way syncing will not process. Consider the following while making updates the metafield:

  • Data columns keys are provided as keys on the JSON object, which are case sensitive.
  • Any keys that don’t match a corresponding data column will be ignored.
  • You need only to provide custom data column keys within the value, not Shopify fields (first_name, for example).

Here’s an example JSON request with two custom data columns:

{
  "resource": "customers",
  "resource_id": 934237493428,
  "namespace": "customer_fields",
  "key": "data",
  "value_type": "json_string",
  "value": "{\"journey_destination\": \"Mordor\", \"use_eagle_transport\": false}"
}

 

Custom data types

The data metafield is of the json_string type, allowing all of its contents to be used like any other proper liquid variable.

For instance, date columns can have date filters applied to them:

{{ custom_data["birthday"] | date: "%a, %b %d, %y" }}
Mon, Jun 8, 98

integer and float columns can have math filter applied to them:

{{ custom_data["some_float"] | plus: custom_data["some_integer"] }}
5.4

… and so on!

Access legacy data

We’ve changed how we add custom data to metafields since December, 2019 with our new forms feature. This drastically improved issues with Shopify’s rate limits and thus updates to metafields are no longer delayed. Here’s an example of how it used to be, accessing a key called birthday:

{{ customer.metafields.customr["birthday"] }}

Now, all custom data is store under a new namespace and a single key:

{{ customer.metafields.customer_fields.data["birthday"] }}

But what if you still have old metafields? You’ll need to use the default filter and fall back to the old metafields path in case the new metafield isn’t present:

{{ customer.metafields.customer_fields.data["birthday"] | default: customer.metafields.customr["birthday"] }}

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 © 2020 Helium Development, LLC