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

# User guide

Segment customers and activate common Apple Wallet and Google Wallet use cases from Klaviyo flows and campaigns with The Wallet Crew data.

The Wallet Crew provides two key building blocks inside Klaviyo:

* profile properties to target customers based on wallet state
* pass download links personalized with `neostore.authenticationToken`

## Send an email to customers without an installed pass

This pattern targets profiles where the token exists, but the wallet status indicates “not installed”.

{% stepper %}
{% step %}

#### Build the segment

A dynamic segment can be created that matches:

* `neostore.authenticationToken` is set
* and at least one wallet provider status is not installed

Wallet status is usually exposed as profile properties similar to:

* `neostore.wallet.loyaltyCard.Apple`
* `neostore.wallet.loyaltyCard.Google`

Segment logic often uses:

* Apple status is not equal to `Installed`
* OR Google status is not equal to `Installed`

{% hint style="info" %}
Wallet status properties depend on the type of pass and on tenant configuration.

The safest validation is inspecting one synced profile in Klaviyo and copying the property path. Previewing a few matched profiles also helps.
{% endhint %}
{% endstep %}

{% step %}

#### Create the campaign

A campaign can then target this segment.

This keeps messaging focused on customers who did not adopt wallet yet.
{% endstep %}

{% step %}

#### Insert a pass download link

Klaviyo templates can insert the token with:

`{{person | lookup:'neostore.authenticationToken' }}`

Two common destinations exist: `/mail` opens the pass download and registration layout, and `/mail/confirm` opens the pass page. The full link patterns are in the [Reference](https://docs.thewalletcrew.io/connectors/marketing-automation/klaviyo/reference.md#authenticated-link-patterns).

{% hint style="info" %}
The hostname can differ when a custom domain is configured for the tenant.

Validation can start in Klaviyo preview mode by confirming the rendered URL contains a non-empty `neo.authToken` value.
{% endhint %}
{% endstep %}
{% endstepper %}

## Send an email after pass installation

This pattern starts a flow after an installation metric is recorded.

{% stepper %}
{% step %}

#### Confirm the installation metric exists

The metric appears in Klaviyo once the first install event is received.
{% endstep %}

{% step %}

#### Create a metric-triggered flow

1. Create a new flow.
2. Use a **metric trigger**.
3. Select the **Wallet Installed** metric.
   {% endstep %}

{% step %}

#### Add the message content

The pass page link pattern can be reused for post-install messaging. This is useful for “welcome” and “next step” messages.

In many cases, the confirmation URL (`/mail/confirm`) is preferred here because the pass already exists.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
The install metric is named `Wallet Installed` (and `Wallet Uninstalled` for removals). The metric names are fixed.

See [Reference](https://docs.thewalletcrew.io/connectors/marketing-automation/klaviyo/reference.md).
{% endhint %}

## Send a wallet notification

Wallet notifications can be triggered from a Klaviyo flow using a webhook action calling The Wallet Crew Klaviyo listener.

<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%2F0qclenoWo3cs0lJkFUcy%2Fimage.png?alt=media&amp;token=788c00c0-5b3c-499e-8537-301beada28a8" alt="Wallet notification received on a phone, example for a birthday offer" width="262"><figcaption><p>Wallet notification example for birthday</p></figcaption></figure></div>

This pattern fits any high-intent moment in the customer journey. Wallet lifecycle events, orders, store visits, and milestones can become triggers. Klaviyo orchestration can then combine segmentation, timing, and frequency rules to keep wallet messages timely and relevant.

{% columns %}
{% column %}

<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%2Fgit-blob-c2f79a88c6cc42b3c77c8d44d76e6a3faf5e005c%2Fklaviyo-flow-webhook-action.png?alt=media" alt="Klaviyo flow: webhook action configuration for a wallet notification" width="211"><figcaption><p>Post wallet install webhook flow.</p></figcaption></figure></div>
{% endcolumn %}

{% column %}

<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%2FPSxQ7pWbGqh8k6Ra9Ul0%2Funknown.png?alt=media&amp;token=1bab184a-3fd4-4be6-9c03-858524e5583e" alt="Klaviyo flow with a trigger, a one-hour wait and a webhook step" width="219"><figcaption><p>Post order webhook flow</p></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% hint style="info" %}
Notification behavior differs between Apple Wallet and Google Wallet.

Details: [Push notifications](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/automatisation/push-notifications.md).
{% endhint %}

{% stepper %}
{% step %}

#### Create the flow

Configuration example:

* Flow name: `Post installation`
* Trigger: “when someone wallet installed”
  {% endstep %}

{% step %}

#### Add a webhook action

Use The Wallet Crew Klaviyo listener endpoint:

`https://<host>/api/<tenantId>/webhooks/listeners/klaviyo/passes/pushUpdate` (see the [Reference](https://docs.thewalletcrew.io/connectors/marketing-automation/klaviyo/reference.md#webhook-endpoints))
{% endstep %}

{% step %}

#### Use the JSON payload below

The payload identifies the pass and adds a notification message in `additionalData`.

{% code title="Klaviyo webhook body (JSON)" %}

```json
{
  "identifiers": {
    "id": "{{ person| lookup:'neostore.wallet.loyaltyCard.passId' }}"
  },
  "additionalData": {
    "message_body": "Welcome to the family, {{ person.first_name }}! Earn points on every purchase and unlock rewards along the way."
  }
}
```

{% endcode %}

{% hint style="info" %}
`neostore.wallet.loyaltyCard.passId` exists only for loyalty-card passes (pass templates of the customer card type). For other types of pass, no pass identifier is written on the Klaviyo profile: identify the pass with an external identifier (`id.<key>`) instead.

The update changes the pass. A lock-screen message appears only if a field of the pass template displays `additionalData.message_body` with a change message.
{% endhint %}
{% endstep %}
{% endstepper %}

## FAQ

<details>

<summary><strong>Can a wallet notification be sent if the pass is not installed?</strong></summary>

No. Wallet notifications require at least one active installation on a device.

A common fallback uses email or SMS to distribute a pass download link first, then triggers wallet notifications after an installation event.

</details>

<details>

<summary><strong>How to validate that personalization works before sending a campaign?</strong></summary>

Profile validation can be done by confirming `neostore.authenticationToken` exists on a few test profiles. Setup details: [Setup](https://docs.thewalletcrew.io/connectors/marketing-automation/klaviyo/setup.md).

</details>

<details>

<summary><strong>What is the safest way to test wallet notifications?</strong></summary>

Most teams use staging first and keep a small list of internal test passes installed on real devices.

Notification behavior and limits depend on Apple Wallet and Google Wallet rules. Reference: [Push notifications](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/automatisation/push-notifications.md).

</details>

<details>

<summary><strong>Do authenticated links replace Add to Wallet buttons?</strong></summary>

No. Authenticated links are often used inside email and SMS. Web and app entry points usually use Add to Wallet buttons and dedicated layouts.

</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/user-guide.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.
