> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/connectors/marketing-automation/klaviyo/setup.md).

# Setup

Connect The Wallet Crew and Klaviyo securely, then validate that wallet events and profile properties sync correctly between both platforms.

This setup connects **Klaviyo** (segmentation, flows, campaigns) to **The Wallet Crew** (wallet execution and lifecycle signals).

Klaviyo needs two things:

* credentials so The Wallet Crew can send events and update Klaviyo profile properties
* a webhook flow so Klaviyo can request a back-population of `neostore.authenticationToken` for existing profiles

## Prerequisites

Access is required on both sides.

* **The Wallet Crew**: access to the admin console and to advanced configuration files.
* **Klaviyo**: access to create API keys, segments, flows, and webhooks. Klaviyo requires a **2FA-compliant** account to enable webhooks.
* A test profile exists in Klaviyo with a known email and/or phone number.
* Target environment is identified (staging vs production).

## The Wallet Crew configuration

The Wallet Crew uses the Klaviyo connector to send wallet lifecycle events into Klaviyo, maintain profile properties, and optionally manage list subscriptions based on consent collected in enrolment flows.

### Configure the connector in The Wallet Crew

Open the Klaviyo integration settings in The Wallet Crew admin console (**Data & integrations → Connectors → Marketing automation → Klaviyo**).

<p align="center"><a href="https://admin.thewalletcrew.io/tenant/~/integrations/klaviyo" class="button secondary" data-icon="chevrons-right">Open Klaviyo connector settings</a></p>

The general settings store the Klaviyo Site ID and the Klaviyo private API key.

**Required Klaviyo values**

Klaviyo values are available at `https://www.klaviyo.com/settings/account/api-keys`.

* **Site ID** (`siteId`) maps to **Public API Key / Site ID** in Klaviyo.
* **Private API key** (`privateApiKey`) is a **new** private key created for The Wallet Crew.

**Required permissions on the Klaviyo private key**

Minimum permissions depend on the enabled features.

* Always required
  * Events: **Full Access**
* Required when list subscription sync is enabled
  * Lists: **Full Access**
  * Profiles: **Full Access**
  * Subscriptions: **Full Access**

<div data-with-frame="true"><figure><img src="https://3852727835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlP7d71aYydav6e0pRkxc%2Fuploads%2FWxpWTaMCS0r5wb3KjNiE%2Fdocumentation-klaviyo-todo-alt-image-58-png.png?alt=media&#x26;token=a2184c95-4faa-4dd5-994f-e9f53c1d87e1" alt="Klaviyo API keys screen showing permissions for a private key"><figcaption><p>Make sure the private key permissions match the expected capabilities.</p></figcaption></figure></div>

{% hint style="warning" %}
If events do not appear in Klaviyo, the first check is the Klaviyo private key permissions.
{% endhint %}

### Enable the Klaviyo step in `/server/flows.yml`

The `klaviyo` step sends the registration event when a customer registers through the flow. Install and uninstall events need no flow step: they are sent for every pass as soon as the Klaviyo connector is configured.

{% hint style="info" %}
The `klaviyo` step can be added to any registration flow. In the example, `shopify` is the Shopify connector step of this example tenant; it is not required by Klaviyo. The other steps depend on the flow.
{% endhint %}

{% code title="/server/flows.yml" %}

```yaml
flows:
  - type: userRegistration
    name: user
    steps:
      - type: shopify
      - type: pass
        passType: user
      - type: klaviyo
      - type: mail
        mailTemplate: downloadPass
```

{% endcode %}

### Consent and list subscription configuration

Consent collected in the enrolment form can drive list subscriptions: set **Klaviyo list identifier** and **Enable SMS support** on the **General** tab, as described in [List subscriptions](https://docs.thewalletcrew.io/connectors/marketing-automation/klaviyo/reference.md#list-subscriptions).

## Klaviyo configuration

`neostore.authenticationToken` is the identity cornerstone for authenticated links.

When this property exists on a Klaviyo profile, emails and SMS can include links that open the correct wallet page for that customer.

### Create the “TWC unsynced profiles” segment

This segment targets profiles missing the token.

1. Go to `https://www.klaviyo.com/lists/create` and select **Segment**.
2. Name: `TWC unsynced profiles`.
3. Definition:
   * **Properties about someone**
   * `neostore.authenticationToken`
   * `is not set`

{% hint style="warning" %}
A typo in this rule prevents back-population. This is the most common setup mistake.
{% endhint %}

### Create the profile sync flow

This flow calls The Wallet Crew webhook to sync the token for profiles entering the segment.

{% stepper %}
{% step %}

#### Create a flow

* Go to `https://www.klaviyo.com/flows/create`.
* Create from scratch.
* Name: `sync TWC unsynced profiles`.
* Trigger: “When someone joins TWC unsynced profiles”.
  {% endstep %}

{% step %}

#### Add a webhook action

Set the webhook destination URL:

`https://<host>/api/<tenantId>/webhooks/listeners/klaviyo/profiles/sync` (host: see [Environments and URLs](https://docs.thewalletcrew.io/connectors/marketing-automation.md#environments-and-urls))

`<tenantId>` is the tenant identifier.

Add one header:

* Key: `X-API-KEY`
* Value: an API key created in The Wallet Crew that includes the `tenant.klaviyo.listener` write permission

Body (JSON):

```json
{
  "email": "{{ person.email }}",
  "phone_number": "{{ person.phone_number }}"
}
```

{% endstep %}

{% step %}

#### Enable, then back-populate past profiles

* Enable the flow.
* In the flow menu, use **Add past profiles**.
* Select “from beginning”.
* Run back-population.

This forces existing profiles to be evaluated and synced.
{% endstep %}
{% endstepper %}

## Troubleshooting

These checks explain most “it is configured but nothing happens” situations.

| Symptom                                          | Check                                                                                                                                                                                    |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Events do not appear in Klaviyo                  | The Klaviyo private key has **Events** permission. For registration events, the executed flow includes the `klaviyo` step.                                                               |
| Subscription updates do not work                 | The private key has **Lists**, **Profiles** and **Subscriptions** permissions.                                                                                                           |
| The token is still missing after back-population | The segment rule is exact (`neostore.authenticationToken` **is not set**), the sync flow is **enabled**, and the webhook action shows successful executions in the Klaviyo flow history. |
| The webhook fails                                | The header is `X-API-KEY`. The API key has the `tenant.klaviyo.listener` write permission. The destination URL uses the correct `<tenantId>`.                                            |
| Webhooks cannot be enabled in Klaviyo            | The Klaviyo account is not 2FA-compliant.                                                                                                                                                |
| The link renders without a token                 | The template uses `lookup:'neostore.authenticationToken'`, the profile went through the sync flow, and the token exists on the profile.                                                  |
| Segment logic for installed status is wrong      | The segment checks both Apple and Google properties, and the stored value casing matches the segment condition (example: `Installed`).                                                   |
| Customers land on the wrong page                 | `/mail` opens the registration layout and `/mail/confirm` opens the pass page.                                                                                                           |

## FAQ

<details>

<summary><strong>Is email required to sync <code>neostore.authenticationToken</code>?</strong></summary>

Email is the most common identifier. Phone can also be provided.

The webhook accepts both fields. Matching rules depend on tenant configuration.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/connectors/marketing-automation/klaviyo/setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
