# Helium Customer Fields Notes

Saved: 2026-03-26

## Key links

- Help center collection: https://help.heliumdev.com/en/collections/2040278-customer-fields
- Developer docs home: https://developers.customerfields.com/
- Developer docs, Metafields: https://developers.customerfields.com/metafields/
- Developer docs, Customer API: https://developers.customerfields.com/front-end-api/customer-api/
- Help article, custom namespaces: https://help.heliumdev.com/en/articles/9426266-how-to-use-custom-namespaces-in-customer-fields
- Help article, metafield data in Liquid: https://help.heliumdev.com/en/articles/3554141-metafield-data-in-liquid
- Help article, metafield definitions in Shopify: https://help.heliumdev.com/en/articles/6129087-metafield-definitions-in-shopify
- Help article, app embed: https://help.heliumdev.com/en/articles/6641748-customer-fields-app-embed

## What Customer Fields stores

- Customer Fields stores custom data in two places:
  - the app database
  - Shopify customer metafields
- Standard Shopify fields like `first_name`, `email`, `phone`, and default address are not stored as metafields. They are saved to Shopify customer fields directly.

Source:
- https://help.heliumdev.com/en/articles/3554141-metafield-data-in-liquid

## Namespace behavior

- Helium's default namespace for new custom fields is `app--960624--helium`.
- This is a Shopify app-reserved namespace.
- Helium also supports custom namespaces for form fields and data columns.
- If you need values accessible outside the app's default reserved namespace, configure a custom namespace in the form field's Advanced tab or on the Data columns page.

Source:
- https://help.heliumdev.com/en/articles/9426266-how-to-use-custom-namespaces-in-customer-fields
- https://developers.customerfields.com/metafields/

## Important implication for this project

- We verified in this project that Shopify Admin GraphQL returns `null` for:
  - `app--960624--helium.gender`
  - `app--960624--helium.birthday`
- The same customer still had other admin-visible metafields such as:
  - `customer_fields.access_token`
  - `marketing_consent_sms.marketing_consent_sms`
  - `marketing_consent_whatsapp.marketing_consent_whatsapp`
- This strongly suggests the default Helium app-reserved namespace should not be treated as generally available through our Admin email lookup flow.

Practical result:
- If we need Helium fields like `gender` and `birthday`, the safer path is the storefront/customer-side flow that already returns them.
- If we want email-based Admin API lookup to return those values reliably, Helium fields should be moved or mirrored into a custom namespace that Admin can access for our use case.

## Metafield strategy

- Helium's recommended storage strategy is "Shopify admin-compatible".
- In that mode, each custom data column is stored as its own Shopify metafield with matching metafield definitions.
- Metafield definitions are created automatically when using the compatible strategy.
- Definition type must match the data column type, or writes can fail.

Source:
- https://help.heliumdev.com/en/articles/6129087-metafield-definitions-in-shopify

## Liquid usage examples

- Admin-compatible metafield syntax:
  - `customer.metafields.NAMESPACE.KEY.value`
- Helium's examples often show:
  - `customer.metafields.app--960624--helium.favorite_color.value`
  - `customer.metafields.app--960624--helium.birthday.value`

Source:
- https://help.heliumdev.com/en/articles/3554141-metafield-data-in-liquid

## Front-end API usage

- Helium provides a front-end JavaScript API loaded through the app embed.
- `CF.customerReady(...)` waits until `CF.customer` is available.
- `CF.customer.get(...)` reads data columns.
- `CF.customer.set(...)` stages changes.
- `CF.customer.save(...)` persists them.

Source:
- https://developers.customerfields.com/front-end-api/customer-api/
- https://developers.customerfields.com/front-end-api/customer-api/customer-data/
- https://developers.customerfields.com/installation/

## What `formId` is for

- `formId` is used when saving/submitting customer changes through the Helium front-end API.
- The docs show `formId` being passed to `CF.customer.save({ formId: "..." })`.
- Helium says this tells their servers which form was submitted so they can track submissions and apply form-related behavior such as redirects and tag whitelisting.
- The app embed also uses form IDs to decide which registration/edit-account form to render.

What it is not:
- Helium docs do not describe `formId` as a way to fetch customer metafields directly.
- There is no documented Helium API pattern like "get customer metafields by formId".
- Reading customer data in the front-end API is done with `CF.customer.get("column_key")`, which uses data column keys for the current logged-in customer, not `formId`.

Practical conclusion:
- `formId` identifies the form context.
- Data retrieval is based on the current customer and data column keys.
- If you need customer metafields, use:
  - Shopify APIs / Liquid for metafields, or
  - `CF.customer.get(...)` for logged-in customer data through Helium's front-end API.

Source:
- https://developers.customerfields.com/front-end-api/customer-api/customer-data/
- https://developers.customerfields.com/front-end-api/customer-api/customer-tags/
- https://developers.customerfields.com/guides/building-a-custom-form/
- https://help.heliumdev.com/en/articles/6641748-customer-fields-app-embed

## REST API

- Helium has a REST API for backend changes.
- Their developer docs note REST API access requires the Advanced plan.

Source:
- https://developers.customerfields.com/rest-api/

## Suggested implementation notes

- For our Laravel API:
  - use Admin API when email-only lookup is required
  - use Storefront plus `customer_access_token` when Helium reserved-namespace values are required
- If the business requires `gender` and `birthday` on email-only lookup, ask the Helium app to store those fields in a custom namespace instead of only `app--960624--helium`, or expose them through an app API we can call.