# Sync Metafields

### ℹ️ What are metafields?

* **Product metafields**
* **Variant metafields** (if you enable it)

Tipo app can sync metafields for:

* material, size chart, specifications
* custom badges (e.g. “best\_seller”)
* extra product details used by themes/apps

Metafields are custom fields in Shopify used to store extra product data, such as:

***

### ✅ **Supported metafield types**

* Multi-line text
* Rich text
* Integer
* Decimal
* Date and time
* Date
* Dimension
* Volume
* Weight
* True or false
* Rating
* URL
* Money
* Link
* JSON

🚫 **Not supported yet:**\
Reference types (e.g. product reference, collection reference) are not currently supported.

***

### 🛠️ Step 1: Configure Metafields on the Source Store

1. Open the app > click **Settings** > find **Share Metafields**
2. Tick on the checkbox  **Enable** of **Share Metafields** option > 

   **Allow data**

   * **Product Resource**
   * **Variant Resource**
3. An input to add metafield definitions: **Add definition (namespace.key)**  (optional)
4. Click **Save** to update the changes

<figure><img src="https://2618001169-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQFJLe0hkcyiradJOCgpx%2Fuploads%2FUDBkP3FH5Sondna7Vpf3%2F2025-12-04_15-51-15.png?alt=media&#x26;token=acc17fc9-eb4a-4142-a91e-427a998e6b67" alt=""><figcaption></figcaption></figure>

***

### 🛠️ Step 2: Configure Metafields on the Destination Store

1. Open the app > click **Stores** > click on the source store URL to open the connection detail

<figure><img src="https://2618001169-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQFJLe0hkcyiradJOCgpx%2Fuploads%2FbTtdHi6l6ZfjQPCCcWTZ%2Fopen%20connection.png?alt=media&#x26;token=3ca45f42-0ac2-49a9-8ec0-55aaeb638739" alt=""><figcaption></figcaption></figure>

2. Find **Metafields** sync section > tick **Enable**
3. Choose what to sync

   Under **Allow data**, select one or both:

   * **Product Resource** → sync product metafields
   * **Variant Resource** → sync variant metafields
4. Click on the search icon on the right to see all the supported metafields > click **Select valid metafield to sync** button&#x20;

<figure><img src="https://2618001169-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQFJLe0hkcyiradJOCgpx%2Fuploads%2FC3I76vjk8VZrG22gELtb%2Fimage.png?alt=media&#x26;token=e2028985-57b6-45c3-9e8b-f8cc29b15303" alt=""><figcaption></figcaption></figure>

**Note:**&#x20;

✅ Green: Metafields that already exist in the destination store and are valid to sync.\
⚪ Gray: New metafields that will be created and synced.\
🟠 Orange: Invalid metafields due to mismatched data types between source and destination stores. These must be fixed manually in Shopify.\
🔴 Red: Unsupported metafields that cannot be synced by the app

<figure><img src="https://2618001169-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQFJLe0hkcyiradJOCgpx%2Fuploads%2FA5tXN572PeQ9hFIjCSJL%2F2025-08-04_14-47-53.png?alt=media&#x26;token=8f2e5f32-5930-456b-9bb4-8272a56d2aa3" alt=""><figcaption></figcaption></figure>

5. Click **Save** to update the changes

***

### &#x20;🔄 What Happens During Sync

#### **1) If the Destination store doesn’t have the metafield definition**

The app will automatically create the metafield definition in the Destination store (when needed).

After it’s created, the synced metafield values will appear on the product/variant in the Destination store.

#### **2) If metafields exist but are not “structured” (Unstructured metafields)**

In some cases, metafields may sync even if they haven’t been fully defined/structured in the Destination store.

To review them in Shopify Admin:

* **Settings → Custom data → Metafields and metaobjects**
* Choose **Product** (or **Variant**)
* Open **View unstructured metafields**

💡 Tip: You can manually define/structure these metafields later to keep your store data clean and consistent.

#### **3) If the Source store has no value, Destination won’t be overwritten**

If a metafield exists in Destination but the Source value is empty, Tipo Sync will not overwrite the Destination value.

#### **4) Data types must match (very important)**

Metafield data types must match exactly between Source and Destination.

Examples of data type mismatches:

* `single_line_text_field` vs `multi_line_text_field`
* `number_integer` vs `number_decimal`
* `product_reference` vs `text`

⚠️ If the data types don’t match, the sync may fail or skip that metafield.

***

### 📌 Example: Syncing a Product Metafield – “Material”

You want to sync a **custom product metafield** called **Material** (e.g., “Cotton”, “Leather”, “Wool”) from your **Source Store** to your **Destination Store** using our app.

#### **Step 1: Define the Metafield in Shopify**

In your **Source Store**:

1. Go to **Shopify Admin > Settings > Custom Data > Products**
2. Click **Add definition** (if it’s not already created) > fill out the metafield definition:
   * **Name**: Material
   * **Namespace**: `custom`
   * **Key**: `material`
   * **Type**: Single line text

\=>  This gives you the full metafield key: `custom.material`

Repeat this step in your **Destination Store** (must match the same key and type).

#### **Step 2: Add Metafield Data to Products**

In your **Source Store**, go to a product and scroll down to **Metafields**  > Under **Material**, enter: `Cotton`

This product now has the metafield `custom.material = "Cotton"`.

#### **Step 3: Configure Sync in Tipo app**&#x20;

* Open our app in the **Destination Store > g**o to **Connect Configuration > Metafield Sync**
* Choose **Specific Metafields > e**nter the metafield key exactly: `custom.material`

**Result**

* Our app will find `custom.material` in the Source Store
* If it does **not exist** in the Destination product, the app will **create it**\
  \=>   Result: `custom.material = "Cotton"` in both stores
* If it exists in Destination but Source is empty, we **do not override** the value

***

### ❓FAQs

#### Q1: How to Set `namespace.key` in your store?

To sync a specific metafield, you’ll need to enter the **metafield definition key** in this format: `namespace.key` (for example: `custom.color`).

Here’s how to find it in your Shopify admin:

1. Go to your Shopify Admin >cavigate to **Settings > Custom Data > Products**
2. Click on the metafield you want to sync\
   → You’ll see the **Namespace** and **Key** values
3. Combine them in this format: `namespace.key`\
   → Example: `custom.description`

#### Q2: Why are my metafields not syncing?

If your metafields are not syncing correctly, it could be due to one of the following reasons:

1. **Metafield sync is not enabled**\
   Make sure metafield syncing is turned on for both stores:
   * Enable **Share Metafields** in the **Source Store**.
   * Enable **Receive Metafields** in the **Destination Store**.

<figure><img src="https://2618001169-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQFJLe0hkcyiradJOCgpx%2Fuploads%2Fkfh2ymXGwUs2wUgC6CBC%2F2025-12-04_15-51-15.png?alt=media&#x26;token=90fdb57b-7c81-47ce-86c7-8a1e29f6c566" alt=""><figcaption></figcaption></figure>

2. **Metafield definition key is not added**

Besides enabling metafield sync, you must also add the **metafield definition key (namespace.key)** that you want to sync.

* Go to **Settings → Share Metafields**
* Make sure **Enable** is checked
* Under **Allow data**, add the metafield definition in this format:\
  `namespace.key`\
  Example: `custom.material`

<figure><img src="https://2618001169-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQFJLe0hkcyiradJOCgpx%2Fuploads%2FPUgw8d0OkKUGQS88g8ou%2F2026-03-03_14-04-49.png?alt=media&#x26;token=191b7771-8dca-4f8e-8520-a32b2535af20" alt=""><figcaption></figcaption></figure>

3. **Unsupported metafield types**\
   Some metafield data types are not supported, such as **Reference types** or **MetaObjects**.

Red: Unsupported metafields that cannot be synced by the app

<figure><img src="https://2618001169-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQFJLe0hkcyiradJOCgpx%2Fuploads%2FVDfNX9flDYXpF9wNaR7n%2Fimage.png?alt=media&#x26;token=b3ff512c-cd75-40ae-a1c7-5108b3fd5beb" alt=""><figcaption></figcaption></figure>

4. **Mismatched metafield types between stores**\
   The metafield in your Source and Destination must have **the same data type and structure**.\
   Common mismatches include:

* One metafield is **Single line text**, while the other is **Multi-line text**.
* One metafield uses **Single value**, while the other uses **List of values**.

To fix these issues, confirm that metafields in both stores have the same **namespace**, **key**, and **data type**, then try syncing again.

***

**🙋 Still need support?**

If you still need help, please feel free to contact us at <hi@tipo.io>. We’ll be happy to assist you further.