> For the complete documentation index, see [llms.txt](https://docs.shopwaive.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shopwaive.com/shopify/email-and-campaigns/klaviyo-events.md).

# Klaviyo events

Send each balance moment to Klaviyo as a Shopwaive metric: connect with your one Klaviyo key, build a flow on a metric, and see when each metric fires and which properties it carries

Klaviyo events send each balance moment to Klaviyo as a Shopwaive metric: a customer earning a balance, redeeming it, getting it back, losing it when it expires, or pressing **Redeem**. A Klaviyo flow can start each time the moment happens, and its message can show that moment's values, such as the amount.

In Shopwaive the feature is the **Klaviyo balance events** card, under **Settings** > **Integrations**, below the balance sync card.

Balance events and [Klaviyo balance sync](https://docs.shopwaive.com/shopify/email-and-campaigns/klaviyo-email-and-sms.md) use one Klaviyo key and do different jobs:

* **Balance sync** keeps one number on each profile, `shopwaive_balance`: the customer's balance now. Use it in segments, and to show the balance in a message.
* **Balance events** send one event for each moment, with that moment's own values. Use them to start a flow when the moment happens.

An event never writes a profile property, and no event property has a name that starts with `shopwaive_`.

## The Klaviyo key <a href="#the-klaviyo-key" id="the-klaviyo-key"></a>

Balance events and balance sync use the same Klaviyo private API key. Create it once, with these four permission scopes, and use it for both. Klaviyo's form names the access levels No Access, Read Access and Full Access.

| Scope        | Level       | What Shopwaive does with it                                                                                                                                   |
| ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Accounts** | Read Access | Balance sync and balance events read the name of your Klaviyo account.                                                                                        |
| **Events**   | Full Access | Balance events create the events. Read Access is not enough: Full Access is the only level that lets a key create events.                                     |
| **Metrics**  | Read Access | Balance events read your account's metrics once, to check the key.                                                                                            |
| **Profiles** | Full Access | Balance sync writes `shopwaive_balance`. Balance events only read profiles, to check that the key belongs to the Klaviyo account that balance sync writes to. |

Leave every other scope at No Access. The steps to create the key are in [Step 1](https://docs.shopwaive.com/shopify/email-and-campaigns/klaviyo-email-and-sms.md#step-1-create-a-private-api-key-in-klaviyo) of the balance sync page.

Klaviyo shows a key only once, and does not let you add a scope to a key that exists: see Klaviyo's [How to create or clone a private API key](https://help.klaviyo.com/hc/en-us/articles/7423954176283).

* If your balance sync key was created with only Accounts and Profiles, create a new key with all four scopes and save it in balance sync (**Replace key**, then **Save new key**): balance events connect with it too. You can then delete the old key in Klaviyo.
* If your balance sync key has the four scopes and you no longer have it, create one new key with all four scopes and save it in balance sync (**Replace key**, then **Save new key**): balance events take it too.

To replace your key, save the new one in balance sync: balance events take it too.

## Connect events <a href="#connect-events" id="connect-events"></a>

{% stepper %}
{% step %}
In your Shopify admin, open Shopwaive, then **Settings** > **Integrations**.
{% endstep %}

{% step %}
Connect balance sync with your one Klaviyo key, made with the four scopes above. Balance events connect with the same key at the same time.
{% endstep %}

{% step %}
Under **Events sent to Klaviyo**, tick the moments you want to send.

<figure><img src="https://1743155819-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6HSAZj4RDucpQwVtzMYt%2Fuploads%2Fgit-blob-902f8e8a97c0fa7ba3f2f5f69593a30a47e464fb%2Fsettings-klaviyo-events.png?alt=media" alt="The Klaviyo balance events card in Settings, Integrations: the events sent to Klaviyo, each with a box"><figcaption><p>Settings, Integrations: choose the events sent to Klaviyo</p></figcaption></figure>
{% endstep %}

{% step %}
On a Balance store, type your three-letter currency code, such as USD, under **Currency** and click **Save currency**.
{% endstep %}
{% endstepper %}

Shopwaive checks the key with Klaviyo. The card then reads "Connected to" followed by your Klaviyo account name, and shows the checkboxes described under [Which events are sent](#which-events-are-sent). Paste the key into Shopwaive yourself. Do not email it to support.

The email address for test events is optional:

* **With an address**, connecting also sends one test `Shopwaive: Balance Earned` event to it, so that metric appears in Klaviyo within a few minutes. Use a real address that you can check. A test event never starts a flow.
* **Without an address**, Shopwaive checks the key without creating any event, profile or metric in your Klaviyo account.

Either way, each metric appears in Klaviyo under **Analytics** > **Metrics** with its first event. To see every metric that is switched on without waiting for real events, type an address and click **Send test events**: see [Test events and real events](#test-events-and-real-events).

If the card answers "This key can't read metrics" or "This key can't create events", the key is missing a scope. Create a new key with all four scopes and paste that one.

## Build a flow from a Shopwaive metric <a href="#build-a-flow-from-a-shopwaive-metric" id="build-a-flow-from-a-shopwaive-metric"></a>

A Shopwaive metric starts a flow each time its event arrives, and the flow's messages can show the event's own values. The example below thanks a customer for the points they have just earned.

1. Make sure Klaviyo lists `Shopwaive: Balance Earned`. A metric appears with its first event, or within a few minutes of clicking **Send test events** in the card.
2. In Klaviyo, open **Flows**, click **Create flow**, and choose **Build your own**. Choose the trigger **Metric** and pick `Shopwaive: Balance Earned`.
3. Add a trigger filter on `note`, so that only the deposits you mean start the flow. If your earn deposits carry notes such as `Earned 12.5 Points`, use `note` contains `Earned`. Type the words exactly as your notes write them. The filter needs **Include the deposit note**, which is ticked after you connect.
4. In the trigger settings, leave **Re-entry criteria** at **Allow re-entry**, Klaviyo's default for a metric trigger. The customer then gets the email each time they earn.
5. Add an email to the flow, and show the event's values in it with `{{ event.amount }}` and `{{ event.balance_after }}`, as in the example below.
6. Keep the email in Draft. Check it in **Preview & test** against a real event, then set it to Live.

<figure><img src="https://1743155819-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6HSAZj4RDucpQwVtzMYt%2Fuploads%2Fgit-blob-00e3e0087a57de4ede56fe46a4865de829612804%2Fklaviyo-events-flow-canvas.png?alt=media" alt="" width="450"><figcaption><p>The example flow in Klaviyo: the trigger, then one email in Draft</p></figcaption></figure>

<figure><img src="https://1743155819-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6HSAZj4RDucpQwVtzMYt%2Fuploads%2Fgit-blob-c4358f635bca92636f7b4092f93cbedb8c065b09%2Fklaviyo-events-flow-trigger.png?alt=media" alt="" width="450"><figcaption><p>The trigger: the metric, Re-entry criteria at Allow re-entry, and the trigger filter</p></figcaption></figure>

In the example, the email's subject line and preview text carry the two tags:

```
Subject line: You earned {{ event.amount }} points
Preview text: Your balance is now {{ event.balance_after }} points
```

<figure><img src="https://1743155819-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6HSAZj4RDucpQwVtzMYt%2Fuploads%2Fgit-blob-8e3813cac89d01864c60a32e99b467a40390424e%2Fklaviyo-events-flow-email.png?alt=media" alt="" width="450"><figcaption><p>The email: in Draft, with the two tags in its subject line and preview text</p></figcaption></figure>

* **No Time Delay is needed here.** Both values come from the event itself, and `{{ event.balance_after }}` is the balance just after this deposit. A message that shows `{{ person.shopwaive_balance }}` instead needs a Time Delay: see [When events arrive](#when-events-arrive).
* **A test event shows placeholders**, 0 for every number and `test` for text. Check the email against a real event before you set it to Live.
* **On a Balance store**, write the amounts as money, for example `${{ event.amount }}`.
* **Smart Sending** can skip an email when the customer was emailed recently. Decide per email whether to keep it on: see [Smart Sending](https://docs.shopwaive.com/shopify/email-and-campaigns/klaviyo-email-and-sms.md#smart-sending).

Klaviyo's own pages: [How to create a metric-triggered flow](https://help.klaviyo.com/hc/en-us/articles/360003057151), [Understanding flow triggers and filters](https://help.klaviyo.com/hc/en-us/articles/115002779051) and [How to use event data to personalize email and SMS flows](https://help.klaviyo.com/hc/en-us/articles/115002779071).

### Flows for other moments

| To message a customer when               | Trigger                                      | Then                                                                                                                  |
| ---------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| they earn points                         | **Metric**: `Shopwaive: Balance Earned`      | A trigger filter on `note`, as in the example above.                                                                  |
| a welcome deposit lands                  | **Metric**: `Shopwaive: Balance Earned`      | The trigger filter `note` equals the note of your welcome deposit, and **Re-entry criteria** set to **No re-entry**.  |
| they redeem their balance                | **Metric**: `Shopwaive: Balance Redeemed`    | No filter is needed. `{{ event.amount }}` is the amount used, and `{{ event.balance_after }}` what is left.           |
| a redeemed balance is given back         | **Metric**: `Shopwaive: Balance Refunded`    | No filter is needed.                                                                                                  |
| their points have expired                | **Metric**: `Shopwaive: Balance Expired`     | See [Build a flow on Balance Expired](#build-a-flow-on-balance-expired).                                              |
| their points are about to expire         | **Date property**: `shopwaive_expiry_date`   | See [Klaviyo expiry properties](https://docs.shopwaive.com/shopify/email-and-campaigns/klaviyo-expiry-properties.md). |
| their balance reaches a level you choose | **Added to segment**, on `shopwaive_balance` | See [In a flow](https://docs.shopwaive.com/shopify/email-and-campaigns/klaviyo-email-and-sms.md#in-a-flow).           |

Klaviyo cannot change the trigger of a flow that exists. To move a flow that is triggered by a list or a segment onto a Shopwaive metric, save its emails as templates, then build a new flow on the metric and add the saved templates: see Klaviyo's [How to change a flow trigger](https://help.klaviyo.com/hc/en-us/articles/115002775052).

## The seven metrics

| Metric                               | When it fires                                                                                            | After you connect                                                                                                       |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `Shopwaive: Customer clicked Redeem` | **Redeem** was pressed and Shopwaive created the discount or gift card for it. No balance has moved yet. | On                                                                                                                      |
| `Shopwaive: Balance Earned`          | A deposit reached the customer's wallet.                                                                 | On                                                                                                                      |
| `Shopwaive: Balance Redeemed`        | A paid order used the customer's balance.                                                                | On                                                                                                                      |
| `Shopwaive: Balance Refunded`        | A balance that the customer had redeemed was given back.                                                 | On                                                                                                                      |
| `Shopwaive: Balance Expired`         | Points or a balance expired.                                                                             | On where Shopwaive has switched it on for your store, otherwise off. See [Balance Expired](#shopwaive-balance-expired). |
| `Shopwaive: Balance Adjusted`        | A balance was set to a new value, or lowered, outside a redemption or an expiry.                         | Off. You switch it on in the card.                                                                                      |
| `Shopwaive: Balance Imported`        | A bulk import, added by Shopwaive support as history.                                                    | No checkbox. It never starts a flow.                                                                                    |

Shopwaive sends each name exactly as it is written here and never renames it. In Klaviyo, a metric is listed under **Analytics** > **Metrics**, with the source API, once an event for it has arrived.

## Properties that the metrics share

| Property              | Type   | Example         | Meaning                                                                                                                 |
| --------------------- | ------ | --------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `store`               | Text   | `your-store`    | Your store's handle: the part of your myshopify.com address before `.myshopify.com`.                                    |
| `unit`                | Text   | `points`        | `points` on a Loyalty and Rewards store, `money` on a Balance store.                                                    |
| `points_multiplier`   | Number | `1`             | Your **Multiplier for display** when it is above 1, otherwise 1.                                                        |
| `currency`            | Text   | `USD`           | The three-letter currency code, on a Balance store, when Shopwaive knows it. Never sent on a Loyalty and Rewards store. |
| `shopify_customer_id` | Text   | `1234567890123` | The customer's Shopify id, when Shopwaive holds it.                                                                     |

`store` is on all seven metrics. The other four are on every metric except Customer clicked Redeem.

How values are sent:

* **Numbers** are plain numbers in the units your store shows, by the same rule as `shopwaive_balance`. On a Loyalty and Rewards store they are whole points, multiplied by your **Multiplier for display** when it is above 1. On a Balance store they are money to two decimals. A number is sent as a number, so 55.30 arrives as 55.3.
* **Points are rounded.** A deposit of 12.5 points arrives with `amount` 13, while its note shows 12.5. A movement that is too small to show, such as 0.4 points, arrives with `amount` 0, and the event is still sent.
* **Amounts are always positive.** The metric says which way the balance moved.
* **Timestamps** are in UTC, in the form `2026-01-15T09:30:00Z`. Format a timestamp in your template before you show it to a customer.
* **True or false** values arrive as true or false, never as text.
* **A value that Shopwaive does not know is left out.** It is never sent empty.

In a flow triggered by the metric, show a property with a tag such as `{{ event.amount }}`. Tags are case-sensitive. Klaviyo's **Preview & test** shows the properties of recent events, and you can copy each tag from it.

Events also carry values that Shopwaive keeps for its own records. They are not in the tables below, and you can ignore them: `lane`, `kind`, `source`, `mode`, `entry_key`, `ledger_seq`, `amount_minor`, `balance_before_minor`, `balance_after_minor`, `order_source`, `code_amount`, `code_currency`, `multiplier_applied`, `requested`, `applied`, `shortfall`, `gift_card_id`, `action_run_id`, `line_item_id`, `lot_id`, `deposited_at`, `expiry_rule`, `refund_id`, `refund_of`, `restorations`, `refund_basis`, `import_id`, `row` and `replayed`.

## Shopwaive: Customer clicked Redeem

It fires when a customer presses **Redeem** at checkout or in their account, or staff press it at the point of sale, and Shopwaive creates the discount or gift card for it. No balance has moved yet.

| Property     | Type   | Example         | Meaning                                                                                                                |
| ------------ | ------ | --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `rail`       | Text   | `discount`      | How the customer is redeeming: `discount` for a discount code, `gift` for a gift card, `gift_b2b` for a B2B gift card. |
| `pre_credit` | Number | `100`           | The customer's balance just before **Redeem** was pressed, when Shopwaive knows it.                                    |
| `code_id`    | Text   | `1461234567002` | The id of the discount or gift card that was created. It is never the code itself.                                     |
| `store`      | Text   | `your-store`    | Your store's handle.                                                                                                   |

* It fires for each press that creates a discount or gift card, whether or not the order is completed.
* When the same customer presses **Redeem** again within 60 seconds, for the same way of redeeming, no second event is sent.
* A customer who creates a gift card from their account page sends this event too.

It does not carry: an amount, the code itself, an order (none exists yet), where **Redeem** was pressed, or `unit`, `points_multiplier`, `currency` and `shopify_customer_id`.

## Shopwaive: Balance Earned

It fires when a deposit reaches a customer's wallet, for example from Shopify Flow's **Increment balance** action, the Shopwaive API, a budget, or a product purchase that is set up to add a balance.

| Property         | Type          | Example                | Meaning                                                                                                                                                              |
| ---------------- | ------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`         | Number        | `13`                   | The amount that was added.                                                                                                                                           |
| `balance_before` | Number        | `25`                   | The balance before the deposit.                                                                                                                                      |
| `balance_after`  | Number        | `38`                   | The balance after the deposit.                                                                                                                                       |
| `note`           | Text          | `Earned 12.5 Points`   | The note that was written with the deposit.                                                                                                                          |
| `first_deposit`  | True or false | `false`                | True when the wallet had no earlier deposit, redemption, refund, expiry or adjustment, false when it had. Bulk imports and deposits to a whole segment do not count. |
| `earn_source`    | Text          | `shopify_flow`         | `shopify_flow` for a deposit made by a Shopify Flow action, `product_flow` for a product purchase that adds a balance, `api` for any other deposit.                  |
| `expires`        | True or false | `true`                 | Whether the deposit expires.                                                                                                                                         |
| `expires_at`     | Timestamp     | `2027-01-15T00:00:00Z` | When the deposit expires. Sent only when `expires` is true.                                                                                                          |
| `order_id`       | Text          | `5001234567890`        | The id of the Shopify order that the deposit names, when it names one.                                                                                               |

* `first_deposit` does not mean one particular welcome deposit. To greet customers when a welcome deposit lands, filter on that deposit's `note`.
* `first_deposit` ignores imported balances. On a store whose customers were imported, the first deposit after the import counts as a first deposit.
* `first_deposit` is left out when Shopwaive cannot tell. Such an event does not match a filter on it.
* A deposit from a product purchase carries no `amount`, `balance_before` or `balance_after`.

It does not carry: a tier or a reward name, or where the deposit was made. A bulk import and a deposit to a whole customer segment are never sent. See [What never sends an event](#what-never-sends-an-event).

## Shopwaive: Balance Redeemed

It fires when a paid order uses the customer's balance, by discount code, gift card, B2B, point of sale or draft order. It fires when Shopify reports the order as paid, which can be a few minutes after checkout.

| Property         | Type   | Example         | Meaning                                                                                                               |
| ---------------- | ------ | --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `amount`         | Number | `200`           | The amount of balance that the order used.                                                                            |
| `balance_before` | Number | `659`           | The balance before the order.                                                                                         |
| `balance_after`  | Number | `459`           | The balance after the order.                                                                                          |
| `order_id`       | Text   | `5001234567890` | The id of the Shopify order.                                                                                          |
| `order_name`     | Text   | `1001`          | The order's number, with no # in front.                                                                               |
| `rail`           | Text   | `discount`      | How the balance was redeemed: `discount` for a discount code, `gift` for a gift card, `gift_b2b` for a B2B gift card. |

It does not carry: a note, the code of the discount or gift card, the items or the total of the order, or a value for Klaviyo's revenue reporting.

## Shopwaive: Balance Refunded

It fires when Shopify Flow's **Refund balance** action gives back a balance that the customer had redeemed.

| Property         | Type   | Example                                                 | Meaning                                                                                          |
| ---------------- | ------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `amount`         | Number | `200`                                                   | The amount that was given back.                                                                  |
| `balance_before` | Number | `459`                                                   | The balance before the refund.                                                                   |
| `balance_after`  | Number | `659`                                                   | The balance after the refund.                                                                    |
| `note`           | Text   | `Refunded (credited) 200 points redeemed on Order 1001` | The note that Shopwaive wrote for the refund.                                                    |
| `order_id`       | Text   | `5001234567890`                                         | The id of the Shopify order whose redemption was given back.                                     |
| `rail`           | Text   | `discount`                                              | How the balance had been redeemed, when Shopwaive recorded it: `discount`, `gift` or `gift_b2b`. |

It does not carry: the refund of the order itself. That is a Shopify moment. When an order is refunded in full, Klaviyo's Shopify integration sends it as its own metric, Refunded Order. Klaviyo does not receive that event for a partial refund: see Klaviyo's [Shopify data reference](https://help.klaviyo.com/hc/en-us/articles/115005080447).

## Shopwaive: Balance Expired <a href="#shopwaive-balance-expired" id="shopwaive-balance-expired"></a>

It fires when points or a balance expire in Shopwaive.

* On a store where each deposit has its own expiry date, one event is sent for each deposit that expires. A customer whose three deposits expire together gets three events.
* On a store that expires each customer's whole balance on a single date, one event is sent for the whole balance.

Balance Expired is switched on per store by Shopwaive. Where it is switched on, it is on from the moment you connect and its checkbox in the card is ticked. If your store expires balances and the checkbox is not ticked, contact Shopwaive support.

To remind customers before their points expire, use the [Klaviyo expiry properties](https://docs.shopwaive.com/shopify/email-and-campaigns/klaviyo-expiry-properties.md) instead. This metric fires after the points are gone.

### Before you build on Balance Expired

* **It starts when it is on.** Expiries recorded before Balance Expired was on are not sent. One exception: an expiry recorded in the six hours before can still arrive.
* **One event for each expired deposit.** A metric-triggered flow starts for every event, so a customer whose deposits expire together would get one message for each deposit. Limit how often one customer can enter the flow. See [Build a flow on Balance Expired](#build-a-flow-on-balance-expired).
* **The amount belongs to one event.** Where each deposit has its own expiry date, `amount` is one deposit's amount. It is not the total that the customer lost that day.
* **Expiry comes in bursts.** Many customers' points can expire in the same hour, and every event counts towards your store's two [daily caps](#daily-caps). If one day brings more events than a cap allows, the events past the cap are not sent as they happen, and no flow starts for them. On a store that expires each customer's whole balance on a single date, one expiry can reach every customer at once, and the card says so under the checkbox.
* **Test events are optional.** To see the metric and its properties in Klaviyo before the first real expiry, click **Send test events** in the card while the checkbox is ticked.
* **Keep the flow in Draft** until a real event has arrived and you have checked it in **Preview & test**.

### Properties of Balance Expired

| Property         | Type      | Example                | Meaning                                                                                                                                                    |
| ---------------- | --------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`         | Number    | `20`                   | The points or balance that expired with this event: one deposit's amount, or the whole balance on a store that expires the whole balance on a single date. |
| `balance_before` | Number    | `659`                  | The balance before this expiry.                                                                                                                            |
| `balance_after`  | Number    | `639`                  | The balance after this expiry.                                                                                                                             |
| `expired_at`     | Timestamp | `2026-10-15T00:13:08Z` | When Shopwaive recorded the expiry.                                                                                                                        |
| `note`           | Text      | `19.97 Points expired` | The note that Shopwaive wrote for the expiry.                                                                                                              |
| `reference`      | Text      | `6118420000001`        | The id of the deposit that expired. You can ignore it. It is not sent when a whole balance expired.                                                        |

* `amount`, `balance_before` and `balance_after` are on the event when Shopwaive recorded them with the expiry. An event without them still carries `expired_at` and `note`. Before you show one of them in a message, check a real event from your store in **Preview & test**.
* `amount` is rounded the way your store shows a balance, and the note is not. In the example above, 19.97 points expired, `amount` is 20, and the note reads 19.97. Show the amount or the note in one message, not both.
* When several deposits expire together, each event carries its own `balance_before` and `balance_after`. Only the last one carries the balance that the customer ends with.

It does not carry: the date on which the points were due to expire, the total that the customer lost that day, or the note of the deposit that expired.

### Build a flow on Balance Expired

1. In Klaviyo, open **Flows**, click **Create flow**, and choose **Build your own**. Choose the trigger **Metric** and pick `Shopwaive: Balance Expired`. Klaviyo lists the metric once its first event has arrived, or once you click **Send test events** in the card.
2. If your store's events carry `amount`, add the trigger filter `amount` is at least 1. It keeps out an expiry that is too small to show, whose `amount` is 0.
3. In the trigger settings, set **Re-entry criteria** to **Allow re-entry after a time period**, for example 1 day. A customer whose deposits expire together then gets one message.
4. Add a **Time Delay** of at least 10 minutes before the message. Balance sync and balance events are separate, so an event can reach Klaviyo before the new `shopwaive_balance` does. When many balances change at once, balance sync needs longer: see [Timing](https://docs.shopwaive.com/shopify/email-and-campaigns/klaviyo-email-and-sms.md#timing).
5. Write the message. To show the balance the customer has now, use `{{ person.shopwaive_balance }}`, which needs balance sync to be connected.
6. Keep the message in Draft until a real event has arrived. Check it in **Preview & test**, then set the message to Live.

A message that works on every store:

```
Some of your points have expired. Your balance is now {{ person.shopwaive_balance }} points.
```

If your store's events carry the amount:

```
{{ event.amount }} points expired. Your balance is now {{ person.shopwaive_balance }} points.
```

With a re-entry limit, the message is sent for the first event of that period, and `{{ event.amount }}` is that one deposit's amount. On a Balance store, write the amounts as money.

Klaviyo describes **Re-entry criteria** in [How to create a segment- or list-triggered flow](https://help.klaviyo.com/hc/en-us/articles/360003040052), and says there that it manages re-entry the same way for every flow type. That page also says the setting is still reaching some accounts. Klaviyo's steps for the trigger are in [How to create a metric-triggered flow](https://help.klaviyo.com/hc/en-us/articles/360003057151).

## Shopwaive: Balance Adjusted

It fires when a balance is set to a new value, or lowered, outside a redemption or an expiry:

* a balance is set to a new value, by staff in Shopwaive, by Shopify Flow's **Set balance** action or through the API;
* a deposit is voided;
* a decrease is sent through Shopify Flow's **Increment balance** action with a negative amount, through the API, or removed at the point of sale;
* a product purchase lowers or resets a balance.

This metric is off until you tick its checkbox in the card. It is off by default because a correction made by your staff would become a lasting record on the customer's profile in Klaviyo.

| Property         | Type   | Example                        | Meaning                                                                                                                                                                                                                                        |
| ---------------- | ------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`         | Number | `60`                           | The size of the change.                                                                                                                                                                                                                        |
| `balance_before` | Number | `100`                          | The balance before the change.                                                                                                                                                                                                                 |
| `balance_after`  | Number | `40`                           | The balance after the change.                                                                                                                                                                                                                  |
| `direction`      | Text   | `down`                         | `up` when a set raised the balance. `down` or `void` when the balance was lowered.                                                                                                                                                             |
| `set_target`     | Number | `40`                           | The balance that a set aimed for, or the balance that a product purchase left.                                                                                                                                                                 |
| `adjust_source`  | Text   | `api`                          | Shopwaive's label for how the change was made: `admin`, `api`, `shopify_flow`, `void` or `product_flow`. A set that raised the balance reads `admin`. A decrease reads `shopify_flow` when a Shopify Flow action made it, and `api` otherwise. |
| `note`           | Text   | `Balance corrected by support` | The note that was written with the change.                                                                                                                                                                                                     |
| `order_id`       | Text   | `5001234567890`                | The id of the order that the change names, when it names one.                                                                                                                                                                                  |

* A voided deposit arrives as a decrease, with the `direction` `down` or `void`.
* A change made by a product purchase carries no `amount`, `balance_before` or `balance_after`.

It does not carry: the name of the staff member who made the change.

## Shopwaive: Balance Imported

A bulk import of balances never sends an event while it runs. Shopwaive support can add an import to Klaviyo afterwards, as history under this metric. It never starts a flow, and it has no checkbox in the card and no test event. It has no properties to build on.

## Test events and real events

Test events are optional. In the connected card, **Send test events** sends one test event for each metric that is switched on, to the address in **Email address for test events**. The card says: "Optional: send one test event for each metric that is turned on, so every metric and its properties can be picked in Klaviyo before the first real event arrives. Test events can't trigger a flow."

|                     | Test event                                                                                                                                        | Real event                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| The property `test` | `true`                                                                                                                                            | Not sent                                             |
| Which properties    | Every property name that the metric can carry, with the ones you can ignore                                                                       | Only the values that Shopwaive knows for that moment |
| The values          | Placeholders: 0 for a number, false for true or false, `test` for text, the time of the click for a timestamp. `store` is your real store handle. | The real values                                      |
| Flows               | Never starts a flow. It is marked as a test and sent as history.                                                                                  | Starts the flows that the metric triggers            |

So a property that you can pick in Klaviyo is not always on a real event. Build on the properties in the tables above, and check a real event in **Preview & test** before you set a message to Live.

## Which events are sent

After you connect, the card shows a checkbox for each metric and for each setting.

Under **Events sent to Klaviyo** there is one checkbox for each metric except Balance Imported.

| Checkbox                                                                                                                           | After you connect                                                                                                 | Who changes it    |
| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------- |
| `Shopwaive: Customer clicked Redeem`, `Shopwaive: Balance Earned`, `Shopwaive: Balance Redeemed` and `Shopwaive: Balance Refunded` | Ticked                                                                                                            | You               |
| `Shopwaive: Balance Adjusted`                                                                                                      | Not ticked                                                                                                        | You               |
| `Shopwaive: Balance Expired`                                                                                                       | Ticked where Shopwaive has switched it on for your store, otherwise not ticked. It cannot be changed in the card. | Shopwaive support |

Under **What each event carries** there are two more checkboxes. Both are ticked after you connect.

* **Include the deposit note** sends `note`. The card says: "The note is sent to Klaviyo as it is written, with email addresses removed from it." A note longer than 512 characters is cut and ends with "…".
* **Include order identifiers** sends `order_id`, `order_name` and `shopify_customer_id`. It also covers four of the values you can ignore: `refund_id`, `line_item_id`, `action_run_id` and `lot_id`.
* The card says of both: "An event that has been sent can't be changed or taken back from here, so turning this off only affects events sent from now on."

On a Balance store the card also shows **Currency** with the button **Save currency**: "The three-letter currency code sent with each event, such as USD." Shopwaive uses it when the balance change itself names no currency.

## Daily caps

Each store has two daily limits, which the card calls caps. One limits how many events are sent to Klaviyo in a day. The other limits how many events are queued in a day, which means taken in by Shopwaive to be sent. A day runs from midnight to midnight UTC. Each cap is 5,000 unless the card shows another number.

The card shows both numbers, with today's counts, in a line that starts "Daily caps (UTC day):". When your store reaches a cap, events stop until Shopwaive support releases it. Balance changes made after the cap was reached are not sent as they happen. Shopwaive support can add them to Klaviyo afterwards as history, which never starts a flow.

## When events arrive

* **Usually within about a minute of the change.** Shopwaive reads balance changes once a minute and sends them in order. Klaviyo then processes each event, and can take a few minutes to show it.
* **Each event carries the time of the change itself**, not the time it was sent.
* **Balance Redeemed** follows Shopify reporting the order as paid, which can be a few minutes after checkout.
* **A late event is history.** An event that is sent more than five and a half hours after the change is recorded as history and does not start a flow.
* **The balance can arrive after the event.** Before a message that shows `{{ person.shopwaive_balance }}`, add a **Time Delay** of at least 10 minutes.

## What never sends an event

* **A bulk import of balances.**
* **A deposit made to a whole customer segment at once.**
* **Records that do not move a balance**, such as a balance email, or a customer's Shopwaive account that is created without a deposit.
* **A customer's Shopwaive account that is deleted.** No event is sent for the balance that goes with it.
* **A change whose amount is exactly 0.** A change that is only too small to show is sent, with `amount` 0.
* **Anything balance sync does.**
* **A metric that is switched off.**
* **A customer whose email address in Shopwaive is not a usable address.**
* **Moments that happen in Shopify**: orders, order refunds, fulfillment, new or updated customers, tags, discounts and gift cards that are created, and Shopify's native store credit.
* **Reward thresholds.** Shopwaive sends no event when a balance crosses a threshold. For a threshold, use a segment on `shopwaive_balance`.

## Customer data in events

* **An event names the customer by email address only**, so that Klaviyo can find the profile. Apart from the note, no property holds the customer's name, an address, the items of an order, or the code of a discount or gift card.
* **The note is the one piece of free text.** Email addresses in a note are replaced by `[email removed]` before it is sent. Any other personal detail in a note is sent as it is written, so keep personal details out of deposit notes, or untick **Include the deposit note**.
* **An event for an address that has no profile in Klaviyo creates the profile.** Klaviyo counts profiles towards your plan, as described under [Before you start](https://docs.shopwaive.com/shopify/email-and-campaigns/klaviyo-email-and-sms.md#before-you-start).
* **Shopwaive cannot change or delete an event once it is sent.**

Questions? Send us a message in the in-app chat or email <support@shopwaive.com>.
