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

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.
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.
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.
Go to
https://www.klaviyo.com/lists/createand select Segment.Name:
TWC unsynced profiles.Definition:
Properties about someone
neostore.authenticationTokenis not set
Create the profile sync flow
This flow calls The Wallet Crew webhook to sync the token for profiles entering the segment.
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-KEYValue: an API key created in The Wallet Crew that includes the
tenant.klaviyo.listenerwrite permission
Body (JSON):
Troubleshooting
These checks explain most “it is configured but nothing happens” situations.
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
Last updated

