Profile field mapping

Any Omneo Profile attribute can be synced into a Shopify customer metafield. The mapping surface is general purpose, so you are not limited to a fixed list of supported fields: if the value exists on the Omneo Profile and a metafield exists in Shopify to receive it, you can connect the two without an Omneo release.

This page covers Profile field mapping. For mapping Shopify product fields into Omneo, see the product Field mapping section in Setting up the Shopify extension.

Configuration is two steps, in this order.

Create the metafield in Shopify

Shopify will not store a value in a metafield that has no definition, so the metafield must exist before you can map to it.

Map the field in the Omneo CX app

Choose the Omneo field, choose the Shopify field, and the extension writes the value on every sync.

Fields you do not need to map

A core set of fields syncs by default in both directions. Do not create mappings for these. Custom mappings are applied on top of the defaults and are resolved last, so a custom row targeting one of these fields overrides the default behaviour, which is rarely what you want.

Shopify Account to Omneo Profile

Applied on every sync, on both create and update:

Omneo Profile field	Source	Behaviour
`first_name`	Shopify first name	Falls back to `Unknown`. On update, `Unknown` is dropped so it never overwrites an existing name.
`last_name`	Shopify last name	Same fallback and update behaviour as `first_name`.
`email`	Shopify email	Falls back to `{customerID}@example.com` when the Shopify record has no email.
`mobile_phone`	Shopify phone	Written only when a phone number exists.
`tags`	Shopify tags	Filtered by the tag whitelist, prefixed, then sorted.
`joined_location_id`	Default or POS location	Written only when a location resolves and the Profile does not already have one.

Applied only when the Profile is first created:

Omneo Profile field	Source	Behaviour
`identities`	Identity handle and Shopify customer ID	The primary matching identity, plus any additional mapped identities. See Mapping Identities.
`joined_at`	Shopify created date	Recorded in UTC.
`preferred_location_id` and `joined_location_id`	Default location	Written only when a default location is set.
`region_id`	Default region	Written only when a default region is set.
`attributes.comms`	Marketing consent	Email and SMS opt-in state with consent timestamps. Skipped when marketing updates are disabled, except on first create.
`statuses`	Shopify customer state	Set to `['guest']` when a newly created Shopify Account is disabled.
`addresses`	Shopify addresses	Each address that has an `address1`, mapped and linked back to Shopify.

Omneo Profile to Shopify Account

Shopify field	Source	Behaviour
`firstName`	`first_name`	Skipped when the value is `unknown`.
`lastName`	`last_name`	Skipped when the value is `unknown`.
`email`	`email`
`phone`	`mobile_phone_e164`
`tags`	Omneo tags	Prefixed, `cx-` by default.
`metafields[omneo.balance]`	Balance fields	Always written. See The legacy balance metafield.
Marketing consent	`attributes.comms`	Email and SMS consent state.
Addresses	Profile addresses	Written on create.

Step 1: Create the metafield in Shopify

Go to Settings > Custom data > Customers in Shopify admin:

https://admin.shopify.com/store/[tenant]/settings/custom_data/customer/metafields

Select Add definition and create one definition for each Omneo value you want to sync.

Definition settings

Setting	What it does	Guidance for Omneo fields
Name	The human readable label shown wherever the metafield appears in Shopify admin.	Name it for the business meaning, not the Omneo field path. Use `Omneo Tier`, not `tier.name`. Prefixing with `Omneo` groups the synced fields together visually.
Namespace and key	The unique identifier for the metafield, in `namespace.key` form. Shopify prefills it from the name and restricts it to letters, numbers, underscores, and dashes.	Replace the default `custom` namespace with `omneo`. This separates Omneo owned values from fields the merchant maintains by hand, and it matches the namespace the extension already uses for `omneo.balance`.
Type	The content type of the value, chosen from Shopify’s list of presets, for example single line text, integer, date, or JSON.	Match the shape of the Omneo attribute. Text values such as a Tier name are `Single line text`. Point balances are `Integer`. Structured payloads are `JSON`.
One or List of	The selector to the left of the content type. One stores a single value. List of stores an ordered array of values of that type.	Use One unless the Omneo attribute genuinely holds multiple values. A mapping that writes a single string into a list type will not validate.
Description	Optional free text explaining what the field holds and where it comes from.	Say that Omneo owns the value, so nobody on the merchant team edits it by hand and wonders why it reverts. For example, “The Profile’s current Omneo tier”.
Validation	Optional rules constraining accepted values. The available rules depend on the type, for example minimum and maximum length for text, minimum and maximum for numbers, or a list of allowed choices.	Leave validation open unless you are certain of the value set. A validation rule that the Omneo value fails rejects the write, and the field then stays stale.

The type of a definition cannot be changed after it is saved. Changing a type means deleting the definition, which deletes the stored values, and creating it again. Confirm the type before you save.

Options

Option	What it does	Guidance for Omneo fields
Storefront API access	Exposes the metafield to the Storefront API so Liquid themes and custom storefronts can read it.	Turn on for any value the storefront needs to display, such as a tier badge or a points balance. Leave off for internal values.
Customer Account API access	Controls what a signed-in Profile can do with the metafield through the Customer Account API. Shopify offers no access, read, and read and write.	Grant the lowest level the experience needs. Omneo is the system of record for these values, so read is the right default. Read and write allows the Profile to overwrite what Omneo synced, which the next sync then reverses.
Filter or group data in Analytics	Makes the metafield available as a filter and grouping dimension in Shopify Analytics.	Turn on for values the merchant will report on, such as tier or lifecycle status.
Definition pinned	Pins the metafield to the top of the Shopify Account detail page in admin so staff see it without expanding the metafields section.	Pin the handful of fields that store and service staff actually use. Leave the rest unpinned.

Step 2: Map the field in the Omneo CX app

Go to Omneo CX > Settings > Profiles in Shopify admin and open the Field Mapping tab:

https://admin.shopify.com/store/[tenant]/apps/omneo-cx/app/settings/profiles?tab=mapping

The Profile settings screen carries five tabs. Field Mapping is the last of them.

Tab	Purpose
Identity	The Omneo identity handle that links Omneo Profiles to Shopify Accounts, and the mapping of additional Identities. See Mapping Identities.
Tags & Sync	Tag whitelist, tag prefix, and sync controls.
Webhook Filters	Which Shopify webhook events the extension acts on.
Marketing	Marketing consent handling.
Field Mapping	Per field mapping between Omneo and Shopify, covered here.

Mappings are applied every time a Profile is synced.

Anatomy of a mapping row

Select Add mapping to create a row. Each row is one field, in one direction.

Control	What it does
Omneo and Shopify pills	Show the direction of the mapping, reading left to right. `Omneo → Shopify` writes an Omneo value into Shopify.
Omneo field	The source attribute on the Omneo Profile, in dot notation. Nested values are addressed through their parent, for example `tier.name`.
Shopify field	The destination on the Shopify Account. Native fields and any customer metafield defined in Step 1 are both valid targets. Metafields are addressed as `namespace.key`, for example `omneo.current_tier`.
Enter manually	Switches the selector to a free text input. Use it when the field you need does not appear in the list, which happens with newly created metafields and with less common Omneo attributes. Type the exact path, because it is not validated against a schema.
Format	Optional. Resolves the value through a format instead of copying it across unchanged. Product mapping offers `Direct` and `Template` formats, documented in Setting up the Shopify extension. Check the options presented on the row for the formats available to Profile mapping.
Array Select	Optional. For source attributes that hold an array, selects which entry is used instead of writing the whole array.
Default	Optional. A fallback value used when the source attribute is empty.
Delete icon	Removes the mapping. Values already written to Shopify are not cleared, so remove the mapping and then clear the metafield if the value must not persist.

Format, Array Select, and Default are available independently on each side of the row.

Mapping Identities

An Identity is an external ID associated with an Omneo Profile: the named slot that holds a Profile’s unique identifier in a third-party system, such as a Shopify customer ID, a loyalty card number, or a staff number. Each Identity has a handle and an identifier, referenced together as handle:identifier, for example shopify:12345. Identities are what let Omneo unify one person’s data across every system that knows them. See Identities for the concept and Working with identities for the API.

Identities cannot be mapped through a Field Mapping row. The extension filters identities out of field mapping in both directions, because Identities are attached through the dedicated Identities API rather than written as a Profile attribute. A mapping row that targets identities is ignored.

Map Identities in the Identity tab of Profile settings instead. That tab handles two things:

Setting	Purpose
Identity handle	The handle used for the primary link between an Omneo Profile and a Shopify Account, `shopify` by default. Do not change this once Profiles have started syncing.
Identity mapping	Maps additional Omneo Identities to Shopify fields, including custom metafields, so an external ID held in Omneo can be written into Shopify and used there.

Identity mapping uses the same row model as Field Mapping: a source, a destination, and the optional modifiers. The difference is which side of the Profile the value is read from.

The Shopify Extension claims the shopify handle. Do not reuse it for a mapped Identity, and do not point another Extension at it. Handle collisions cause the owning Extension to behave incorrectly.

Sync behaviour

Mapped fields update automatically whenever the underlying attribute changes on the Omneo side. You do not need to trigger anything.
Before launch, run a bulk resync so existing Profiles are brought up to date. New mappings apply from the moment they are saved, so without a resync the values populate slowly as each Profile happens to change.
A mapping writes on sync only. Editing a metafield by hand in Shopify admin holds until the next sync of that Profile overwrites it.
Custom mappings are resolved after the default field mapping, so a custom row pointed at a default target wins. Use this deliberately or not at all, because overriding a default such as email or tags changes behaviour the rest of the extension depends on.

Example: syncing the current tier

Mapping the Omneo Tier name into a customer metafield:

Step	Value
Shopify metafield name	`Omneo Tier`
Namespace and key	`omneo.current_tier`
Type	One, Single line text
Description	The Profile’s current Omneo tier
Omneo field	`tier.name`
Shopify field	`omneo.current_tier`

Adapt the pattern to whatever fields and naming approach suit the brand.

Reading the value on the storefront

With Storefront API access enabled, a synced metafield is available in Liquid on the customer object:

{% if customer.metafields.omneo.current_tier %}
  <span class="tier-badge">{{ customer.metafields.omneo.current_tier.value }}</span>
{% endif %}

Syncing to a metafield suits values that are stable between purchases, such as tier or lifecycle status. For values that change often, or that are not synced at all, query Omneo directly using the token flow in Shopify Authentication.

Recommended practice

Record every field you plan to sync in a shared Data Dictionary before you create the definitions: business meaning, Omneo field path, Shopify namespace and key, type, and owner. Metafield types cannot be changed after creation and namespaces are hard to rename once values are live, so agreeing the naming convention up front is much cheaper than correcting it later.

The legacy balance metafield

omneo.balance predates the field mapping system. It is a hardwired feature of the extension, it still works, and it holds a structured array of balance data for the Profile. The extension appends it to every Omneo to Shopify sync, so it is always present and always current without any configuration.

Do not create a definition for omneo.balance or map to it manually. The extension maintains it. Create separate metafields if you need individual balance values in their own fields.

See Setting up the Shopify extension for the rest of the sync configuration, and Shopify for what the extension syncs overall.

Overview

Ecommerce

Communications

ERP and POS

Customer service

Profile field mapping

Fields you do not need to map

Shopify Account to Omneo Profile

Omneo Profile to Shopify Account

Step 1: Create the metafield in Shopify

Definition settings

Options

Step 2: Map the field in the Omneo CX app

Anatomy of a mapping row

Mapping Identities

Sync behaviour

Example: syncing the current tier

Reading the value on the storefront

Recommended practice

The legacy balance metafield

​Fields you do not need to map

​Shopify Account to Omneo Profile

​Omneo Profile to Shopify Account

​Step 1: Create the metafield in Shopify

​Definition settings

​Options

​Step 2: Map the field in the Omneo CX app

​Anatomy of a mapping row

​Mapping Identities

​Sync behaviour

​Example: syncing the current tier

​Reading the value on the storefront

​Recommended practice

​The legacy balance metafield

Fields you do not need to map

Shopify Account to Omneo Profile

Omneo Profile to Shopify Account

Step 1: Create the metafield in Shopify

Definition settings

Options

Step 2: Map the field in the Omneo CX app

Anatomy of a mapping row

Mapping Identities

Sync behaviour

Example: syncing the current tier

Reading the value on the storefront

Recommended practice

The legacy balance metafield