> 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/reference.md).

# Reference

Reference for the Klaviyo connector: link patterns, webhook endpoints, events and profile properties, subscription routing and script hooks.

This page holds the lookup information for the [Klaviyo connector](https://docs.thewalletcrew.io/connectors/marketing-automation/klaviyo.md): authenticated link patterns, webhook endpoints, the events and profile properties The Wallet Crew writes into Klaviyo, subscription routing, and script hooks.

The prefix `neostore` is the platform's former name and is kept in technical identifiers such as `neostore.authenticationToken` and `neo.authToken`.

## Authenticated link patterns

Authenticated links are built on the profile property `neostore.authenticationToken`. Two patterns exist. Authenticated links are often used in email and SMS. Web and app entry points usually use "Add to Wallet" buttons and dedicated layouts instead.

| Link                                                                                                        | Opens                                | Use it when                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `https://<host>/<tenantId>/mail?neo.authToken={{person \| lookup:'neostore.authenticationToken' }}`         | The enrolment or registration layout | The pass is not installed, or a registration step is needed. This is the usual choice for pass download and registration journeys. |
| `https://<host>/<tenantId>/mail/confirm?neo.authToken={{person \| lookup:'neostore.authenticationToken' }}` | The pass page                        | A pass already exists and the goal is to show the pass details.                                                                    |

The host depends on the environment: see [Environments and URLs](https://docs.thewalletcrew.io/connectors/marketing-automation.md#environments-and-urls).

## Webhook endpoints

Klaviyo flows call these endpoints from a webhook action. Each call needs the header `X-API-KEY` with a The Wallet Crew API key that includes the `tenant.klaviyo.listener` write permission. The webhook action requires a Klaviyo account that is 2FA-compliant.

| Endpoint                                                                          | Purpose                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST https://<host>/api/<tenantId>/webhooks/listeners/klaviyo/profiles/sync`     | Syncs `neostore.authenticationToken` for the profile identified by `email` and/or `phone_number`. The holder must have an email address in the tenant's customer system; otherwise the request is ignored. See [Setup](https://docs.thewalletcrew.io/connectors/marketing-automation/klaviyo/setup.md).                               |
| `POST https://<host>/api/<tenantId>/webhooks/listeners/klaviyo/passes/pushUpdate` | Updates a pass (same changes as `PATCH /passes`) and returns `202`. A lock-screen message appears only if a field of the pass template displays the `additionalData` key with a change message. See the [User guide](https://docs.thewalletcrew.io/connectors/marketing-automation/klaviyo/user-guide.md#send-a-wallet-notification). |

The `pushUpdate` body accepts:

* `identifiers`: `id` alone (the pass identifier), or one or more external identifiers `id.<key>`. Combining `id` with other identifiers is refused (400).
* `passType` (optional): the pass template to move the pass to.
* `additionalData`: values merged into the pass data. Keys not sent keep their current value.
* `updateMetadata` (optional, default `false`): also re-reads the holder's data from connected systems. Slower.

Pass updates can also go through the Pass API. Wallet notifications are covered in [Push notifications](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/automatisation/push-notifications.md) (Engage guide). API details and required permissions: [API reference](https://docs.thewalletcrew.io/api-reference/).

{% hint style="warning" %}
Start in staging. Validate on a test pass. Roll out in production once payloads and targeting are stable.
{% endhint %}

## Events sent from The Wallet Crew to Klaviyo

| Metric                            | Sent when                                                            | Event properties                                                                                                              |
| --------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `Neostore - Customer registered`  | A customer registers through a flow that includes the `klaviyo` step | The account fields (except `debug*` fields), plus the `additionalEventProperties` of the flow step                            |
| `Wallet Installed`                | A pass is installed                                                  | `neostore.wallet.passId`, `neostore.wallet.passType`, `neostore.wallet.device` (`Apple` or `Google`), `neostore.wallet.state` |
| `Wallet Uninstalled`              | A pass is removed                                                    | Same as `Wallet Installed`                                                                                                    |
| `Neostore - Profile synchronized` | The `profiles/sync` webhook processes a profile                      | None                                                                                                                          |

Install and uninstall events can also be backfilled for existing customers with installed passes. A pass can be installed several times (multiple devices or re-install), so install events can fire more than once: design metrics and segments with this in mind.

## Profile properties managed by The Wallet Crew

| Property                             | Content                                                                                                                                                                                                        |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `neostore.authenticationToken`       | Synced to new and existing profiles. Enables authenticated links in Klaviyo templates.                                                                                                                         |
| `neostore.wallet.loyaltyCard.Apple`  | Installation status on Apple Wallet of the holder's loyalty card pass. Values: `Installed`, `Uninstalled`.                                                                                                     |
| `neostore.wallet.loyaltyCard.Google` | Installation status on Google Wallet of the holder's loyalty card pass. Values: `Installed`, `Uninstalled`.                                                                                                    |
| `neostore.wallet.loyaltyCard.passId` | The identifier of the loyalty card pass. The [User guide](https://docs.thewalletcrew.io/connectors/marketing-automation/klaviyo/user-guide.md#send-a-wallet-notification) uses it in the notification payload. |

`loyaltyCard` is a fixed name, not a pass template name. The three `neostore.wallet.loyaltyCard.*` properties are written only for passes whose template is of the customer card type (loyalty card), whatever the template is called. No property is written for other types of pass.

## List subscriptions

Consent collected in the enrolment form can drive Klaviyo list subscriptions. The connector reads these account keys: `email` with `consents_email`, and `phoneNumber` with `consents_sms`. The values of `consents_email` and `consents_sms` may arrive as a boolean or as text, depending on the form.

Set **Klaviyo list identifier** (`listId`) and **Enable SMS support** (`EnableSmsSupport`) on the **General** tab of the Klaviyo connector (**Data & integrations → Connectors → Marketing automation → Klaviyo**).

* **Single list**: set **Klaviyo list identifier** (the value is in the Klaviyo list settings). `consents_email` controls the email subscription when `email` is present.
* **SMS**: with the configured list, `consents_sms` is used only when **Enable SMS support** is checked (default off). Otherwise it is ignored.
* **No list**: the value `builtin` updates the Klaviyo built-in consents with no list relationship.
* **Several lists**: a script returns the subscriptions (below). Script subscriptions are added on top of the configured list: clear **Klaviyo list identifier** to use only the script.

### Multiple lists with a script

The slot `extensions.klaviyo.subscriptions.provider` returns a list of `{ ListId, Email, Sms }` objects. `ListId` can be null for a consent update with no list. The slot file is `/server/scripts/klaviyo.subscriptions.provider.js`. In the admin console, it is the **Subscriptions provider** script on the **Advanced** tab of the Klaviyo connector.

Use it for example to route `consents_email` to a "Newsletter" list and `consents_sms` to a "VIP SMS" list, or to route by store, language or program. The handlers, the synchronous rule and a worked example are in the [Klaviyo scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/klaviyo.md) page of the Developers guides.

## Custom profile mapping

The slot `extensions.klaviyo.mapper` runs after the standard mapping. The standard mapping copies email, last name, first name, country, city and post code (or zip code) into the Klaviyo profile. Use the .NET member names of the Klaviyo profile object (`PhoneNumber`, `Email`, `FirstName`, `Location`), not the JSON names. The slot file is `/server/scripts/klaviyo.mapper.js`. In the admin console, it is the **Profile mapper** script on the **Advanced** tab of the Klaviyo connector.

The handlers and a worked example are in the [Klaviyo scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/klaviyo.md) page of the Developers guides, and the general rules for scripts (globals, handlers, deployment) are in its Scripting section. A scheduled task of type `klaviyo.syncProfile` also exists for profile sync.

## Rollout and safety

A script change affects every profile that goes through an enrolment flow once deployed.

* Start in staging and validate on a small set of test profiles.
* Monitor events and profile properties in Klaviyo.
* Roll back by removing the script entry point, then re-test.


---

# 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/reference.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.
