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:

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:

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:

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

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

Voucher Issued (shopper.voucher-issued)

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

Shopper Opted-In (shopper.opted-in)

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

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.