Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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).

Open Klaviyo connector settings

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

Klaviyo API keys screen showing permissions for a private key
Make sure the private key permissions match the expected capabilities.

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.

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.

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.

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

Create the profile sync flow

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

1

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”.

2

Add a webhook action

Set the webhook destination URL:

https://<host>/api/<tenantId>/webhooks/listeners/klaviyo/profiles/sync (host: see 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):

3

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.

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

Is email required to sync neostore.authenticationToken?

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

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

Last updated