# Metafield Settings

{% hint style="info" %}
This feature is available for **Essential plan and above**.
{% endhint %}

Joy provides two metafield settings that help you connect loyalty data with Shopify's native customer system:

1. **Show metafields on Shopify admin** — Push loyalty data (points, VIP tier) to Shopify Customer Metafields so your team can see them directly in Shopify admin.
2. **Sync Shopify metafields to Joy customer data** — Pull customer profile fields (such as birthday) from existing Shopify metafields into Joy.

***

### Show metafields on Shopify admin

This setting creates structured metafield definitions on your Shopify store and syncs customer loyalty data into them — **Point Balance** and **VIP Tier name** (if your VIP Tier program is active). Once enabled, your team can view this data on any customer's detail page inside Shopify admin without opening Joy.

#### How to enable

{% stepper %}
{% step %}
**Go to Settings → General in Joy**
{% endstep %}

{% step %}
**Scroll to "Show metafields on Shopify admin" and click Turn on**

Joy creates metafield definitions on your store and immediately starts syncing all existing customers in the background.
{% endstep %}

{% step %}
**(Optional) Enable "Allow third-party app access"**

Toggle this on if you want external apps (e.g., Klaviyo, email marketing tools) to read loyalty metafields via the Storefront API. When off, metafields are private to Joy only.
{% endstep %}

{% step %}
**Click "Sync metafields data" to backfill existing customers**

After sync completes, a timestamp shows the last run. Joy then keeps metafields updated automatically in real time.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
To see the data in Shopify admin, go to **Customers → \[any customer]** and scroll to the Metafields section. Joy fields appear under the `$app:joy_loyal` namespace.
{% endhint %}

{% hint style="success" %}
**Tip:** Once this setting is on, you can use loyalty data (Point Balance, VIP Tier) as filters and columns inside **Shopify Analytics reports** — for example, revenue by tier or retention by points. See [Joy data in Shopify Analytics](https://help.joy.so/analytics/shopify-analytics) for setup and example reports.
{% endhint %}

***

### Sync Shopify metafields to Joy customer data

This setting pulls data from your store's existing Shopify Customer Metafields into Joy. Most useful when customer profile fields (like birthday) are already stored in Shopify via another app or manual entry.

#### How to enable

{% stepper %}
{% step %}
**Go to Settings → General in Joy**
{% endstep %}

{% step %}
**Scroll to "Sync Shopify metafields to Joy customer data" and click Turn on**
{% endstep %}

{% step %}
**Enter your metafield namespace and click Get metafields**

Common namespaces: `facts`, `custom`. Not sure which to use? In Shopify admin, go to **Settings → Custom data → Customers** to see all metafield definitions and their namespaces.
{% endstep %}

{% step %}
**Map the metafield to the Joy field and save**

For example, map `facts.birthdate` → **Birthday**. Joy reads this value whenever a customer is created or updated in Shopify and syncs it automatically — no manual import needed.

Fields you can map: Birthday, Phone number, Instagram username.
{% endstep %}
{% endstepper %}

***

### FAQ

#### **Why is VIP Tier not appearing in Shopify admin after I enable this?**

The VIP Tier metafield is only created if your VIP Tier program is active. Go to **Membership → VIP Tiers**, make sure the program is on, then toggle "Show metafields on Shopify admin" off and back on to re-trigger creation.

#### **Does Joy sync metafields automatically, or do I need to click the sync button every time?**

Joy updates metafields in real time when a customer's points or tier changes. The "Sync metafields data" button is a one-time backfill for existing customers — click it once after enabling, or after making configuration changes.

#### **Can other apps like Klaviyo or Omnisend read the loyalty metafields?**

Only if you enable **Allow third-party app access**. When disabled, metafields are private to Joy and cannot be read via the Storefront API.

#### **What happens if I turn off "Show metafields on Shopify admin"?**

Turning it off deletes the structured metafield definitions from Shopify. Customer records will no longer show Joy fields in Shopify admin. The `avada_joy` unstructured namespace (used internally by Joy) is not affected.

#### **What is the difference between the two metafield settings?**

They work in opposite directions. "Show metafields on Shopify admin" pushes loyalty data **from Joy into Shopify** so your team can view it in Shopify admin. "Sync Shopify metafields to Joy" pulls profile data **from Shopify into Joy** — for example, syncing a birthday stored in a Shopify metafield into Joy's customer record.