> For the complete documentation index, see [llms.txt](https://docs.fieldsraven.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fieldsraven.app/klaviyo.md).
# Klaviyo
## To sync Shopify metafields with Klaviyo you need to create a "Private API Key" in Klaviyo
## Setup Klaviyo sync in FieldsRaven
{% hint style="warning" %}
**Klaviyo sync only runs when all of these hold.** If a submission never appears in Klaviyo, this list is where to look:
* The raven's resource is **`customer`**.
* Klaviyo sync is enabled on the raven **and** a private API key is available from Settings or the raven's legacy credential.
* The submission resolved a **customer email** — that is what FieldsRaven matches on in Klaviyo.
* The submission reached status **success** or **approved**. A raven with *needs approval* turned on does not sync until the submission is approved.
{% endhint %}
{% hint style="danger" %}
**The profile must already exist in Klaviyo.** FieldsRaven looks the customer up by email and requires an exact match, ignoring case. If no profile matches, the sync fails rather than creating one — so a customer who has never been added to Klaviyo will not appear because of a FieldsRaven submission.
{% endhint %}
### Save the Klaviyo credential
1. Open **Settings** in FieldsRaven.
2. Under **Integration credentials**, enter the Klaviyo private API key.
3. Select **Update integration credentials**.
FieldsRaven never displays a stored integration credential. Leave the field blank on a later visit to preserve the current key; enter a nonblank value only when you want to replace it.
{% hint style="warning" %}
An older Raven that already stores its own Klaviyo key continues to use that key. The legacy Raven credential overrides the credential in Settings, and replacing the Settings credential does not rotate the legacy value.
{% endhint %}
### Enable Klaviyo on a Raven
When creating a customer Raven, toggle **Sync with Klaviyo**. Leave the Raven's API key field blank to use the shop credential from Settings.
Demo ->
{% hint style="info" %}
The sync job is queued **15 seconds** after the metafield write, then runs subject to your shop's queue.
{% endhint %}
## Sync Shopify metafield into Klaviyo customer profile
When you sync a metafield into Klaviyo's customer profiles, property name in Klaviyo will be the metafield's key in Shopify. For example if you're syncing this metafield `customer.metafields.social_media_profiles.facebook` then property name in Klaviyo will be `facebook`
Klaviyo customer property name example
## Sync Shopify JSON metafield into Klaviyo customer profile
When you sync a JSON type metafield, each property of the JSON object becomes a customer property in Klaviyo. Nested objects are flattened with an underscore (`address_city`), and arrays are numbered from 1 (`tags_1`, `tags_2`).
{% hint style="warning" %}
**A JSON object with exactly one top-level key is sent unflattened.** Flattening is skipped in that case, so `{"address": {"city": "Vancouver"}}` arrives in Klaviyo as a nested `address` property rather than as `address_city`. Add a second top-level key, or flatten it yourself before submitting, if you need flat properties.
{% endhint %}
For example, this object:
```json
{
"facebook": "Share on Facebook",
"twitter": "Tweet on Twitter",
"pinterest": "Pin on Pinterest",
"timestamp": `${Date.now()}`
}
```
Or this:
```json
{
"Serial Number": "000123456789",
"Country of Residence": "Canada",
"Where did you purchase your meter?": "Amazon"
}
```
Becomes as follows in Klaviyo:
Sync Shopify JSON metafield into Klaviyo customer profile
