Skip to main content

Shopify customer metafields sync (V2)

Learn what Rivo syncs to Shopify customer metafields, what does not sync, and when to use the deprecated legacy JSON option.

Written by Stuart Chaney

Rivo supports two customer metafield formats in Shopify:

  • Customer Metafields (Recommended) - The current V2 format with individual customer fields.

  • Legacy Customer JSON Metafield (Deprecated) - The older single JSON object kept for backward compatibility.


​
​

What syncs in the recommended V2 format

When Customer Metafields is enabled, Rivo syncs individual customer fields.
​

Core fields

  • account_activated_at

  • first_redeemed_at


​

If your Points program is enabled

  • points_balance

  • credits_balance

  • loyalty_status


​

If Wallet Pass is enabled

  • is_wallet_pass_subscriber


​

If Membership is enabled

  • membership_tier

  • membership_first_joined_date

  • membership_next_billing_date


​

Customer preferences

If you use customer preference questions, each active preference response can also sync as its own customer metafield.


​
​

What does not sync

Rivo does not sync a customer’s full points transaction history to Shopify metafields.
​

Individual earn and redeem entries are not written as separate metafields.
​

Only current customer-level values (such as balances and status) are synced.


​
​

Enable customer metafields (V2)

  1. In Rivo, go to Settings -> Shopify Metafields & Tags.

  2. In Shopify Metafields , enable Customer Metafields (Recommended).

  3. Save your settings.

  4. Optional: In Troubleshooting , use Sync Store to run a full resync for existing customers.


​
​

Find and export customers with credits but no orders

You can use a Shopify customer segment to find customers who have a positive Rivo credits balance and have never placed a Shopify order.
​

Before creating the segment, confirm that:

  • Your Rivo Points program is enabled. The credits balance is only synced while the Points program is enabled.

  • Customer Metafields (Recommended) is enabled under Settings -> Shopify Metafields & Tags.

  • You are using the current individual customer metafields, not the deprecated legacy JSON metafield.

  • You have run Sync Store under Troubleshooting if existing customers still need to be synced.


​

Use the customer credits balance

Choose Rivo Credits Balance (credits_balance). This is the customer’s current credits balance and is stored as a decimal number.
​

Do not use a base or store-level credit value. Store-level values describe program configuration and are not an individual customer’s available balance.
​

Create the segment in Shopify

  1. In Shopify admin, go to Customers -> Segments and create a new segment.

  2. In the segment editor, select Metafields, then use autocomplete to choose Rivo Credits Balance. Using autocomplete ensures Shopify inserts the correct app-owned metafield name for your store.

  3. Add the condition that the credits balance is greater than 0.

  4. Add the condition that the number of orders equals 0.

The finished query will look like this:
​

metafields."app--4767275--rivo".credits_balance > 0 AND number_of_orders = 0
​

The number in the metafield name identifies the app in Shopify. Do not type or copy that number if Shopify autocomplete shows a different one. Select Rivo Credits Balance from autocomplete and keep the value Shopify inserts.

  1. Apply the query, confirm the matching customers, and save the segment.


​

Export the segment

Open the saved segment in Shopify, select Export, and follow Shopify’s export dialog to export the customers in that segment. Shopify prepares the customer data as a CSV file.
​

If Rivo Credits Balance is unavailable

Check the following in Rivo:

  • The Points program is enabled.

  • Customer Metafields (Recommended) is enabled under Settings -> Shopify Metafields & Tags.

  • The current versioned metafields are enabled instead of relying only on the deprecated legacy JSON option.

  • Sync Store has been run under Troubleshooting to refresh existing customers.

After the sync has had time to process, return to Shopify’s segment editor and search for Rivo Credits Balance under Metafields again.


​
​

Legacy Customer JSON metafield (deprecated)

Enable Legacy Customer JSON Metafield only if you still rely on older theme or email implementations that use the legacy JSON payload.
​

The legacy JSON payload includes:

  • points_balance

  • credits_balance

  • status

  • vip_tier

  • dob

  • dob_last_updated_at

  • referral_code

This option is deprecated and not recommended for new setups.


​
​

FAQ

Do points entries sync to Shopify metafields?
​

No. Individual points events and redemptions do not sync as separate metafields.
​

Do I need Shopify Plus?
​

No. Availability depends on your Rivo plan features. If you do not see Shopify Metafields settings, contact support to confirm access for your plan.
​

How quickly do updates appear?
​

Metafields are updated after relevant profile and points or preference updates are processed. Timing can vary. If you need a full refresh, use Sync Store.

Related Articles
Did this answer your question?