Mapping enriched customer data to Shopify metafields means writing the output of identity enrichment, things like VIP tier, identity type, employer, social handles, and a confidence score, directly onto the Shopify customer or order object as structured custom fields. Once that data lives in metafields, every other system you run can read it natively: Liquid themes, Shopify Flow, the GraphQL Admin API, Klaviyo, Gorgias, and your own apps, all without calling an external enrichment provider at runtime. You enrich once, store the answer in Shopify, and reuse it everywhere.
The short version for anyone scanning: create a metafield definition under the customer owner with a namespace like sonarid or vip, add keys for vip_tier, identity_type, confidence_score, employer, and social_profiles, then write to them with the metafieldsSet GraphQL mutation as orders come in. Use the right metafield types (single_line_text_field for the tier, number_decimal for confidence, json for the structured profile object) so the values stay queryable and render cleanly. Below we cover the full schema, the exact mutation, the type choices, how SonarID populates these automatically, and the workflows metafields unlock once the data is in place.
Why Metafields Are the Right Home for Enrichment Data
Shopify gives you a fixed set of native customer fields: name, email, address, order count, total spent, and tags. None of them can hold "this customer is a venture investor at a top-tier firm with a 0.92 confidence score." You can push some of that into tags, and tags are useful for coarse segmentation, but tags are flat strings with no type system, no nesting, and no clean way to store a numeric score or a profile object. For a proper VIP taxonomy, pair metafields with tags rather than relying on tags alone, as covered in our guide to a VIP customer tag taxonomy.
Metafields solve the structure problem. They are typed, namespaced custom fields that attach to almost any Shopify resource: customers, orders, products, and more. Because they are first-class Shopify data, they appear in the admin, they are queryable through the Admin API, they render in Liquid, and they can drive Shopify Flow. That makes a metafield the canonical place to persist an enrichment result. Instead of every downstream tool re-querying an enrichment provider and re-paying for it, the answer is cached on the customer record where it belongs. This is the same local-reuse principle that makes customer enrichment economical at scale: pay once, read forever.
Designing Your Metafield Schema for VIP Data
Start by deciding the owner resource. For identity and tier data that describes a person across their lifetime, the customer resource is the right owner because the data is durable. For per-order signals (a flagged residence in an affluent zip, a one-time press detection on a specific purchase), the order resource can make sense. Most merchants put identity on the customer and reserve order metafields for transaction-specific flags.
Next, pick a namespace. A namespace groups related metafields and prevents collisions with other apps. Reserve something like sonarid or vip for enrichment data so it never clashes with your custom or theme namespaces. Within that namespace, define a focused set of keys. A practical schema looks like this:
The type choices matter more than they look. A confidence value stored as text cannot be filtered with a greater-than condition. A social profile flattened into a comma-separated string loses the per-platform structure you need for targeting. Define the schema once, deliberately, and every consumer downstream gets clean, predictable data. For a deeper look at what each of these fields actually represents, see our explainer on identity data in ecommerce.
Writing Enriched Data with the GraphQL Admin API
Metafields are written through the Admin API, and the modern path is the metafieldsSet mutation, which can create or update up to 25 metafields in a single call. You pass the owner ID (the customer's global ID, in the form gid://shopify/Customer/123456789), the namespace, the key, the type, and the value. Values are always sent as strings, even for numbers and JSON; Shopify parses each one according to its declared type.
A typical write attaches several fields to one customer at once: vip_tier set to "gold", identity_type set to "founder", confidence_score set to "0.88", and social_profiles set to a JSON string describing their LinkedIn and Instagram presence. Because metafieldsSet is an upsert, re-running enrichment on a returning customer simply overwrites the prior values, which is exactly the behavior you want for a record that should always reflect the latest signal.
Two implementation notes save real debugging time. First, the metafield definition should exist before you write, ideally created with metafieldDefinitionCreate so the field gets a type, validation rules, and admin visibility. You can write to an undefined metafield, but it will not get validation or show up cleanly in the admin UI. Second, respect the Admin API rate limits. If you are enriching a backfill of historical orders, batch your mutations and pace them, the same way you would for any high-volume job; our notes on API rate limits for real-time enrichment apply directly here.
How SonarID Populates These Fields Automatically
If you are building this yourself, the loop is: receive an order webhook, enrich the email and shipping address, derive a tier and identity type, then write metafields. That is precisely the pipeline SonarID runs for you. On every order, SonarID checks the free signal layer first (corporate email domains, spend and LTV patterns, and affluent zip matching on the shipping address, which is the residence signal that matters most for VIP scoring), then optionally runs a paid full-profile enrichment at $0.05 per enrichment. The result is a scored customer with an identity type and a confidence value.
Rather than locking that intelligence inside a separate dashboard, the value compounds when it is written back to Shopify as metafields. SonarID's identity, tier, and confidence outputs map cleanly onto the schema above, so the moment a VIP is detected, the customer record in your own Shopify admin reflects it. From there, your theme, your Flow automations, and your marketing tools read the data without ever knowing or caring that an enrichment provider was involved. This is the difference between an enrichment tool you visit and an enrichment layer that lives inside your store. For the broader picture of how this connects to your stack, see what a customer enrichment API does.
Reading Metafields in Themes, Flow, and Apps
Once the data is stored, the payoff is how many systems can consume it for free. In a Liquid theme, you reference customer.metafields.sonarid.vip_tier to personalize the storefront: show a concierge banner to platinum customers, surface early access to founders, or simply greet a known VIP by their tier. Because the read happens at render time against data already on the customer, there is no external call and no added latency.
In Shopify Flow, metafields become trigger conditions and branch logic. A flow can listen for an order, check whether customer.metafields.sonarid.confidence_score is above your threshold, and then fan out: tag the customer, send an internal notification, or hold the order for white-glove handling. This turns enrichment into operational automation rather than a passive report. Our workflow automation guide walks through wiring these conditions into outreach and identification flows end to end.
For external tools, metafields are exposed through the Admin API, so anything that can query Shopify can read them. Klaviyo can sync customer metafields into profile properties to power VIP segments and flows. Gorgias and Zendesk can pull tier and identity into ticket views so support routes high-value customers correctly. Your own apps query the keys directly. The metafield becomes the single source of truth that every channel references, which is the foundation of treating your store as a unified customer identity graph.
Keeping the Data Fresh and Trustworthy
Enrichment is not a one-time event. People change jobs, gain followers, and move. The enriched_at timestamp lets you find customers who have not been re-enriched in, say, six months and queue them for a refresh. A disciplined refresh cadence keeps tier and identity accurate without re-enriching everyone constantly, which would waste your enrichment budget. Because every plan has a concrete numeric enrichment cap, treat re-enrichment as a deliberate, scheduled job rather than a blanket re-run.
It also pays to store confidence and act on it. A 0.55 score should not trigger the same white-glove workflow as a 0.9. By keeping the score in a numeric metafield, you let each downstream system set its own threshold: a Slack alert might fire at 0.6, while a personal founder-to-founder outreach email waits for 0.85. The metafield holds the raw signal; each consumer decides how cautious to be. That separation of storage from decision-making is what keeps a metafield-based enrichment layer durable as your playbooks evolve, and it pairs naturally with AI-driven personalization for Shopify merchants that reads these fields to tailor experiences in real time.
The end state is clean: enrich on order, write structured metafields, and let themes, Flow, and every connected app read identity, tier, and confidence natively. You stop paying for the same lookup twice, you stop siloing intelligence in a dashboard nobody opens, and you turn "who is this customer, really" into a field your entire stack can act on the moment an order lands.