# User guide

Klaviyo remains the orchestration layer.

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`

<details>

<summary><strong>Real-world examples</strong></summary>

* A reminder campaign targets customers who did not install the pass.
* A post-install flow welcomes customers with a wallet-specific message.
* A post-install flow triggers a wallet notification with an onboarding message.
* A list subscription update in The Wallet Crew enrolment form drives Klaviyo consent-based messaging.

</details>

### 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 pass kind and on tenant configuration.

The safest validation is inspecting one synced profile in Klaviyo and copying the property path.
{% endhint %}

{% hint style="info" %}
Validation can start by previewing a few matched profiles and checking their wallet status properties.
{% 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.

* Pass download / registration layout

```
https://app.neostore.cloud/<tenantId>/mail?neo.authToken={{person | lookup:'neostore.authenticationToken' }}
```

* Pass page (confirmation)

```
https://app.neostore.cloud/<tenantId>/mail/confirm?neo.authToken={{person | lookup:'neostore.authenticationToken' }}
```

`<tenantId>` is the tenant identifier.

{% 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 installation metric (example: “Wallet Installed”).
   {% 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 exact metric name depends on connector configuration.

The metric appears in Klaviyo as soon as the first event is received.

See [Events & data model](https://docs.thewalletcrew.io/connect/marketing-automation/klaviyo/events-and-data-model).
{% 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://3566051324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWLc8AHXW4tdrAXUBfrYF%2Fuploads%2F4n7PSi88zC4n24uuiDdc%2Fimage.png?alt=media&#x26;token=2b7f0372-eb9f-44bc-93a0-c824b0e00e69" alt="" 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://3566051324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWLc8AHXW4tdrAXUBfrYF%2Fuploads%2F36YbuKMy4aZh6RG8jfMo%2Fimage.png?alt=media&#x26;token=b8ba522c-b099-4f67-9abe-c18e26c35ca5" 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://3566051324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWLc8AHXW4tdrAXUBfrYF%2Fuploads%2F1HTqcxHuuB0girhdFXwM%2Funknown.png?alt=media&#x26;token=36cfa1b4-fa24-44bb-a2fc-d5a8534496c5" alt="Klaviyo flow: webhook payload example used to trigger a wallet notification" width="219"><figcaption><p>Post order webhook flow</p></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

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

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

{% stepper %}
{% step %}

#### Create the flow

Configuration example:

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

{% step %}

#### Add a webhook action

Use The Wallet Crew Klaviyo listener endpoint:

`https://app.neostore.cloud/api/<tenantId>/webhooks/listeners/klaviyo/passes/pushUpdate`

The webhook should include the `X-API-KEY` header with a The Wallet Crew API key that includes `tenant.klaviyo.listener` write permission.
{% 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": "Bienvenue dans la famille MINISO {{ person.first_name }} ! 🤗\nDes points à chaque achat et des cadeaux à la clé. C'est le moment de profiter de vos avantages ! 💖"
  }
}
```

{% endcode %}

{% hint style="info" %}
The property used to resolve the pass id can differ by pass type and tenant configuration.

Validation can start by inspecting one Klaviyo profile and confirming which property stores the pass identifier.
{% endhint %}
{% endstep %}
{% endstepper %}

### Subscribe and unsubscribe behavior

List subscription updates can be driven by The Wallet Crew consent fields.

This requires:

* a Klaviyo private key with Lists + Subscriptions permissions
* a single list `listId` configured, or a multi-list script implementation

Setup details: [Consent and list subscription configuration](https://docs.thewalletcrew.io/connect/marketing-automation/setup#consent-and-list-subscription-configuration).

When consent is captured during enrolment, the connector can subscribe the profile to the configured list. When consent is removed, the connector can update the subscription status accordingly.

### Troubleshooting while building campaigns

#### Link renders but token is empty

* Confirm `neostore.authenticationToken` exists on the profile.
* Confirm the profile has been through the sync flow used for back-population.
* Confirm the template uses `lookup:'neostore.authenticationToken'`.
* Confirm the profile leaves the segment used for token back-population (example: `TWC unsynced profiles`) after the sync flow runs.
* If the token is missing on many profiles, revisit [Setup](https://docs.thewalletcrew.io/connect/marketing-automation/setup#klaviyo-configuration).

#### Customers land on the wrong page

Two URLs exist.

* `/mail` opens the registration layout.
* `/mail/confirm` opens the pass page.

#### Segment logic for installed status is wrong

* Confirm the segment checks both Apple and Google properties.
* Confirm the stored value casing matches the segment condition (example: `Installed`).

### FAQ

<details>

<summary><strong>Who typically owns campaigns?</strong></summary>

Campaigns, segments, and flows are owned in Klaviyo.

The Wallet Crew owns wallet execution and wallet lifecycle events.

</details>

<details>

<summary><strong>Which link should be used: <code>/mail</code> or <code>/mail/confirm</code>?</strong></summary>

`/mail` is usually used for pass download and registration journeys.

`/mail/confirm` is usually used when a pass already exists and the goal is to open the pass page directly.

</details>

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

Validation can start in Klaviyo preview mode by checking that the rendered URL contains a non-empty `neo.authToken`.

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

</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 behaviour and limits depend on Apple Wallet and Google Wallet rules. Reference: [Push notifications](https://docs.thewalletcrew.io/engage-and-animate/push-notification).

</details>

<details>

<summary><strong>How to avoid sending too many wallet notifications?</strong></summary>

Wallet notifications are highly visible. Overuse can cause opt-outs and fatigue.

Klaviyo can enforce frequency caps and eligibility segments. A common guard targets only profiles with an installed pass status and recent activity.

</details>