Klaviyo Integration and Triggers for Spaaza

You can trigger emails and communication flows in Klaviyo when specific events occur in Spaaza. This document explains how to set up the integration, create triggers, and personalize emails using the data Spaaza sends.

Contents

• Setting Up the Klaviyo Integration
• Creating a Trigger in Spaaza
• Supported Event Types
• Klaviyo Payload Format
• Event Payloads Sent by Spaaza
  • Transaction (shopper.transaction)
  • Points Mutation (shopper.points-mutation)
  • Loyalty Level Change (shopper.loyalty-level-changed)
  • Voucher Issued (shopper.voucher-issued)
  • Shopper Opted-In (shopper.opted-in)
• Setting Up Campaign-Specific Triggers
• Practical Notes from Experience

Setting Up the Klaviyo Integration

Before you can use triggers:

1. Create a Klaviyo Private API Key.
   See How to Create a Private API Key in Klaviyo.
2. Connect Klaviyo to Spaaza:
   1. Open Settings in the Spaaza Console.
   2. Under Integrations, click Add an integration.
   3. Select Klaviyo.
   4. Enter your Klaviyo Private API Key.
   5. Click Save.

After completing these steps, your integration will be active.

Creating a Trigger in Spaaza

To send a message when an event happens in Spaaza:

1. Create the email Flow in Klaviyo.
2. In Spaaza Console, go to Settings > Integrations > View all triggers.
3. Click Add a trigger and select Add a Klaviyo trigger.
4. Under Event, choose the event type (e.g., Loyalty Level Changed, Voucher Issued).
5. Enter the subject line of the Flow you created in Klaviyo.
6. Important: The subject line must match exactly between Spaaza and Klaviyo.
7. Click Save.
8. Test the flow by performing the event (e.g., changing a loyalty level).

Supported Event Types

The following Spaaza event types are supported for Klaviyo triggers:

Spaaza event type	Klaviyo endpoint
shopper.transaction	POST {hook.URL}events
shopper.points-mutation	POST {hook.URL}events
shopper.loyalty-level-changed	POST {hook.URL}events
shopper.voucher-issued	POST {hook.URL}events
shopper.voucher-expiring	POST {hook.URL}events
shopper.opted-in	POST {hook.URL}events
shopper.altered (profile sync)	POST {hook.URL}profile-import, then POST {hook.URL}events

Klaviyo Payload Format

Spaaza sends event data to Klaviyo using the Klaviyo Events API envelope format. Payloads are not sent in the raw basket/receipt webhook object shape. Instead, each payload is transformed into a Klaviyo Events API envelope with the following structure:

{
  "data": {
    "type": "event",
    "attributes": {
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": "<eventTrigger>"
          }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "email": "...",
            "first_name": "...",
            "last_name": "..."
          }
        }
      },
      "properties": {
        ... event-specific fields ...
      }
    }
  }
}

<eventTrigger> is the trigger name configured in the Spaaza Console (i.e. the subject line entered when creating the trigger). It is used as both the Klaviyo metric name (data.attributes.metric.data.attributes.name) and the action value in data.attributes.properties.

The profile section identifies the shopper by email, first name, and last name.

The properties section contains event-specific fields which vary depending on the event type. See the sections below for the properties included with each event.

Event Payloads Sent by Spaaza

Transaction (shopper.transaction)

Triggered when a basket transaction is completed in Spaaza. The payload is sent to POST {hook.URL}events and contains transaction details in the Klaviyo Events API envelope format.

The properties sent for a transaction event are:

Property	Description
action	The trigger name (same as <eventTrigger>)
transaction_id	Spaaza transaction ID
retailer_basket_code	The retailer's unique identifier for the transaction
transaction_timestamp	ISO 8601 timestamp of the transaction
transaction_type	Transaction type (e.g. in_store, online)
quantity	Total quantity of items in the transaction
line_item_count	Number of distinct line items
subtotal	Subtotal before shipping
total_value	Total transaction value
total_converted	Total value converted to the chain's base currency
shipping_charge	Shipping charge amount
currency_code	Currency code (e.g. EUR, USD)
country_code	Country code of the transaction (e.g. NL, GB)
fx_rate	Foreign exchange rate applied
store_name	Name of the store where the transaction occurred
store_branch_code	Branch code of the store
member_number	Shopper's member number
opted_in	Whether the shopper has opted in to the loyalty programme
join_date	ISO 8601 date when the shopper joined the loyalty programme

Example full payload for shopper.transaction:

{
  "data": {
    "type": "event",
    "attributes": {
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": "Placed Order"
          }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "email": "jane@example.com",
            "first_name": "Jane",
            "last_name": "Doe"
          }
        }
      },
      "properties": {
        "action": "Placed Order",
        "transaction_id": 101,
        "retailer_basket_code": "BASKET-123",
        "transaction_timestamp": "2026-02-12T10:11:12Z",
        "transaction_type": "in_store",
        "quantity": 2,
        "line_item_count": 2,
        "subtotal": 100.5,
        "total_value": 120.75,
        "total_converted": 120.75,
        "shipping_charge": 0,
        "currency_code": "EUR",
        "country_code": "NL",
        "fx_rate": 1,
        "store_name": "Flagship Store",
        "store_branch_code": "ST-01",
        "member_number": "M-123",
        "opted_in": true,
        "join_date": "2025-01-01T00:00:00Z"
      }
    }
  }
}

In this example, "Placed Order" is the <eventTrigger> value configured in the Spaaza Console trigger.

Points Mutation (shopper.points-mutation)

Triggered when a shopper earns or spends loyalty points. The properties sent are:

Property	Description
action	The trigger name (same as <eventTrigger>)
points_amount_earned	Number of points earned in this transaction
points_balance_current	Current total points balance
points_to_proceed_next_level	Points needed to reach the next loyalty level
loyalty_status_level	Current loyalty level name
opted_in	Whether the shopper has opted in
join_date	Date the shopper joined the programme

Loyalty Level Change (shopper.loyalty-level-changed)

Triggered when a shopper's loyalty level changes. The properties sent are:

Property	Description
action	The trigger name (same as <eventTrigger>)
current_level	New loyalty level name
previous_level	Previous loyalty level name
points_balance_current	Current points balance
points_to_proceed_next_level	Points needed to reach the next level
opted_in	Whether the shopper has opted in
join_date	Date the shopper joined the programme

Voucher Issued (shopper.voucher-issued)

Triggered when a voucher is issued to a shopper. The properties sent are:

Property	Description
voucher_id	Unique voucher ID
voucher_key	Voucher key string
voucher_text	Display text of the voucher
voucher_expiry	Voucher expiry date and time
voucher_amount	Monetary value of the voucher
opted_in	Whether the shopper has opted in
join_date	Date the shopper joined the programme

Shopper Opted-In (shopper.opted-in)

Triggered when a shopper opts in to the loyalty programme. The properties sent are:

Property	Description
language	Shopper's language preference
member_number	Shopper's member number
opted_in	Whether the shopper has opted in
join_date	Date the shopper joined the programme

You can access these properties inside your Klaviyo email templates to personalize content based on loyalty status, points earned, vouchers issued, transaction details, and more. Learn how to use dynamic data fields in Klaviyo templates here: Message Personalization Reference - Klaviyo.

Setting Up Campaign-Specific Triggers

You can also link Klaviyo triggers to specific Spaaza campaigns:

1. Open the Campaign page in Spaaza.
2. Click the Triggers tab.
3. Add a new Klaviyo Trigger linked to a campaign event (e.g., Voucher Issued).
4. Follow the same steps as setting a standard trigger.

This allows you to target communications even more precisely during promotions or special events.

Practical Notes from Experience

For Klaviyo integrations with Spaaza:

• Our customer handled most of the setup directly in Klaviyo.
• They created the templates for transactional emails and set up the Flows.
• Spaaza simply posted event payloads to the Klaviyo endpoint.
• After the setup, we collaborated with them to test and confirm everything was working as expected.