Data columns

The Customer Fields app uses data columns to serve data for each customer record. These data columns allow the app to filter, format and import/export customer data in a reliable fashion. There are two main ways to create data columns:

via the Form builder in the app admin
via the Data columns page in the app admin

Overview

Generally speaking, a data column needs to exist in order for the app to save any data for a customer. Data columns are created automatically when adding fields in the app’s form builder, but you can manually create them under the data columns tab.

Each data column has the following attributes:

Label: A human friendly name for the data column.
Namespace: A machine friendly reference to a metafield namespace in Shopify.
Key: A unique, machine friendly name for referencing the data column.
Data type: Indicates the type of data being stored.

Data types

Text: Used for generic multi-line strings of letters & numbers
Single line text: Used for a string excluding newlines
Integer: Used for whole numbers
Float: Used for numbers that contain decimals
Boolean: Used for true/false values
Date: Used for dates (ISO 8601 without a time of day) i.e. 2020-03-19
Datetime: Used for dates (ISO 8601 with time of day) i.e. 2020-03-19T18:08:27.185Z
Email: Used for email addresses
Phone: Used for phone numbers (E.164) i.e. +12535551234
File: Used for files uploaded via embedded forms (files hosted on the app’s CDN)
File reference: Used for file uploads (files hosted on Shopify’s CDN)
List: Used to store multiple values in a single row (array)
Group: Used to store an object of data (e.g. default_address)
Group List: Used to store a list of objects

Group and children data columns

You can setup your data under a specific group data type to help organize data under a single key. This is accomplished by creating a single data column with the type “group” and adding additional columns that begin with the parent’s key followed by a period and child key.

Group

Example data columns:

Key	Data type	Label
dog	group	Dog
dog.name	text	Dog name
dog.breed	text	Dog breed
dog.age	number	Dog age

When getting or setting this data, it results in a data structure as a nested JSON object:

"customer": {
  "first_name": "Kevin",
  "last_name": "Scott",
  "email": "kevin@scott.com",
  "dog": {
    "name": "Snoop",
    "breed": "Corgi",
    "age": 4
  }
}

File type

The file type is very similar to the group type due to its data structure. However, files have a pre-defined set of children data columns contained within them. Here’s an example:

"file": {
  "name": "my-file.jpg",
  "extension": "jpg",
  "type": "image/jpg",
  "size": 321536, // ~314 KB
  "url": "https://files.customerfields.com/.../my-file.jpg"
}

Group list

The same principle applies to the group_list data type:

Key	Data type	Label
dogs	group_list	Dogs
dogs.name	text	Dog name
dogs.breed	text	Dog breed
dogs.age	number	Dog age

Example:

"customer": {
  "first_name": "Elvis",
  "last_name": "Presley",
  "email": "elvis@gmail.com",
  "dogs": [
    {
      "name": "Sammy",
      "breed": "German Shepard",
      "age": 5
    },
    {
      "name": "Barky",
      "breed": "Lab",
      "age": 3
    },
    {
      "name": "Snout",
      "breed": "Pug",
      "age": 4
    }
  ]
}

File reference

The file_reference type references a file that has been uploaded to the shop’s native file system. Files can be uploaded in several ways including the app’s embeded forms, the Shopify Admin UI, and the Shopify Admin API. To set values for this data type you need to pass a string that references the GID of the Shopify file. Here’s an example:

"customer": {
  "first_name": "Frank",
  "last_name": "Smith",
  "email": "frankthetank@example.com",
  "avatar": "gid://shopify/MediaImage/40472197726482"
}

“Standard” Shopify data columns

There are many static data columns that connect the dots to native Shopify functionality. You can find a full list in the app’s UI by clicking on the ‘Standard’ tab on the data columns page. Some of these columns are read-only, while others allow for values to be edited. When submitting data linked to these columns, it’s important to ensure your data is in the correct format. Otherwise, you might run into errors (which you can learn more about here.)

Next up: Metafields