Guides
Start typing to search…

Klaviyo

Klaviyo is a powerful email and SMS marketing platform that combines customer data with intelligent automation to drive personalized marketing campaigns.

Vrio integrates with Klaviyo to automatically sync customer profiles and send real-time event data. This integration ensures all your customer interactions and transaction data are available in Klaviyo for your marketing campaigns.

Getting Started

What You'll Need

  • Active Klaviyo account
  • Private API Key with Read/Write access for Events, Lists, and Profiles
  • Public API Key (optional, for JavaScript tracking)

To get your API keys:

  1. Log into Klaviyo
  2. Navigate to Account page
  3. Select "API Keys"
  4. Create a Private API Key with proper permissions

Quick Setup Guide

  1. Add the Connection

    • Go to Settings > Connections > Add New Connection
    • Find Klaviyo under the "Marketing" category
    • Click "Connect Now"

  2. Enter Your Credentials

    • Connection Name: Something descriptive like "Klaviyo Production"
    • Private API Key: Your Klaviyo private key (required)
    • Push Events: ✓ Check to send customer and order events


  3. Select Campaigns (Optional)

    • Choose specific campaigns to sync
    • Leave empty to sync all campaigns
    • Useful for testing or segmented operations

  4. Save and Activate

    • Click "Save" to complete setup
    • Vrio immediately starts syncing data

How Vrio + Klaviyo Works Together

The Data Flow

When key events happen in Vrio, we automatically send that data to Klaviyo for you to use in your marketing campaigns:

  1. Customer places order → Vrio creates/updates customer profile in Klaviyo
  2. Transaction completes → Vrio sends order details and products purchased
  3. Order ships → Vrio sends fulfillment event with tracking info
  4. Cart abandoned → Vrio sends abandoned order event with cart contents
  5. Subscription changes → Vrio updates subscription status and details

What Data Does Vrio Send to Klaviyo?

When events happen in Vrio, we send data to Klaviyo in two parts: Profile data (always included) and Event-specific properties.

Profile Data (Sent with Every Event)

Vrio always sends customer profile information:

"profile": {
"data": {
"type": "profile",
"attributes": {
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"properties": {
"CLV": "150.00",
"NextChargeDate": "2025-09-15",
"$phone_number": "+15551234567"
}
}
}
}

Event Types and Properties

Customer Created
When Vrio creates a new customer (Customer Created event), we create or update their profile in Klaviyo. No event is triggered, only profile data is sent.

Abandoned Order
When Vrio detects an abandoned cart (Order Abandoned event), we send an Abandoned Order event to Klaviyo with full cart contents (same structure as placed orders).

Placed Order / Placed Non-Recurring Order
When a sale or capture transaction completes successfully in Vrio (Transaction Completed event), we send either Placed Order (for all subscription orders, both new and recurring) or Placed Non-Recurring Order (for one-time purchases). The Cycle field indicates whether it's a new subscription (Cycle: 1) or a recurring charge (Cycle: 2, 3, etc.) with these properties:

"properties": {
  "OrderId": "1253",
  "TransactionId": "1668",
  "SaleId": "1234",
  "Cycle": "1",
  "Attempt": "1",
  "MerchantId": "5",
  "CardLastFour": "4242",
  "Categories": ["Supplements"],
  "ItemNames": ["Monthly Vitamins"],
  "DiscountCode": "SAVE10",
  "DiscountValue": "5.00",
  "Items": [
    {
      "OfferName": "Monthly Vitamins",
      "OfferId": "1",
      "ItemId": "2",
      "ItemName": "Vitamin D3",
      "SKU": "VIT-D3",
      "Quantity": "1",
      "ItemPrice": "29.99",
      "RowTotal": "29.99",
      "Categories": ["Supplements"]
    }
  ],
  "BillingAddress": { /* address details */ },
  "ShippingAddress": { /* address details */ }
}

Declined Order
When a transaction is declined in Vrio (Transaction Completed event for declined type), we send a Declined Order event with all attempted order data including customer information, items, and decline details:

"properties": {
  "OrderId": "1254",
  "TransactionId": "1670",
  "SaleId": "1235",
  "Cycle": "1",
  "Attempt": "1",
  "MerchantId": "5",
  "CardLastFour": "4242",
  "Categories": ["Supplements"],
  "ItemNames": ["Monthly Vitamins"],
  "DiscountCode": "SAVE10",
  "DiscountValue": "5.00",
  "Items": [
    {
      "OfferName": "Monthly Vitamins",
      "OfferId": "1",
      "ItemId": "2",
      "ItemName": "Vitamin D3",
      "SKU": "VIT-D3",
      "Quantity": "1",
      "ItemPrice": "29.99",
      "RowTotal": "29.99",
      "Categories": ["Supplements"]
    }
  ],
  "BillingAddress": { /* address details */ },
  "ShippingAddress": { /* address details */ }
}

Fulfilled Order
When Vrio ships an order (Shipment Shipped event), we send a Fulfilled Order event with all original order data plus shipping details:

"properties": {
  /* All order properties, plus: */
  "ShipDate": "2025-08-30",
  "CarrierName": "UPS", 
  "TrackingNumber": "1Z123456789"
}

Refunded Order
When a refund transaction completes in Vrio (Transaction Completed event for refund type), we send a Refunded Order event showing what was refunded:

"properties": {
  "OrderId": "1253",
  "TransactionId": "1669",
  "SaleId": "1234",
  "Cycle": "2",
  "Attempt": "1",
  "MerchantId": "5",
  "CardLastFour": "4242",
  "Categories": ["Supplements"],
  "ItemNames": ["Monthly Vitamins"],
  "DiscountCode": "SAVE10",
  "DiscountValue": "5.00",
  "Items": [
    {
      "OfferName": "Monthly Vitamins",
      "OfferId": "1",
      "ItemId": "2",
      "ItemName": "Vitamin D3",
      "SKU": "VIT-D3",
      "Quantity": "1",
      "ItemPrice": "29.99",
      "RowTotal": "29.99",
      "Categories": ["Supplements"]
    }
  ],
  "BillingAddress": { /* address details */ },
  "ShippingAddress": { /* address details */ },
  "RefundAmount": "29.99",
  "RefundDate": "2025-08-30",
  "RefundedTransactionId": "1668"
}

Note: Item arrays show specifically refunded items, plus refund-specific details

Voided Order
When a void transaction completes in Vrio (Transaction Completed event for void type), we send a Voided Order event with the same refund-specific fields (RefundAmount, RefundDate, RefundedTransactionId).

Order Chargeback
When a chargeback transaction is recorded in Vrio (Transaction Completed event for chargeback type), we send an Order Chargeback event with full transaction details.

Order Alert
When a fraud alert transaction is recorded in Vrio (Transaction Completed event for alert type), we send an Order Alert event with full transaction details.

Order Auth
When an authorization transaction completes in Vrio (Transaction Completed event for auth type), we send an Order Auth event with full transaction details.

Started Subscription
When a new subscription begins in Vrio (Transaction Completed event, first cycle), we send a Started Subscription event for each subscription item:

"properties": {
  "$event_id": "1668_1_sub",
  "$value": "29.99",
  "ItemNames": ["Monthly Vitamins"],
  "OrderIntervalUnit": "days",
  "OrderIntervalFrequency": "30",
  "DiscountCode": "SAVE10",
  "DiscountValue": "5.00",
  "Items": [
    {
      "OfferName": "Monthly Vitamins",
      "OfferId": "1",
      "ItemId": "2",
      "ItemName": "Vitamin D3",
      "SKU": "VIT-D3"
    }
  ]
}

Cancelled Subscription
When an order offer is cancelled in Vrio (Order Offer Cancelled event), we send a Cancelled Subscription event with the cancellation reason and subscription details.

Subscription Status Changes
When an order offer is updated in Vrio (Order Offer Updated event), we send the appropriate event:

  • Paused Subscription - when subscription is paused
  • Unpaused Subscription - when subscription is resumed
  • Reactivated Subscription - when cancelled subscription is reactivated

Ordered Product
For each item in a completed transaction (triggered by Transaction Completed event in Vrio), we send an individual Ordered Product event:

"properties": {
"$event_id": "1668_1",
"$value": "29.99",
"OfferId": "1",
"OfferName": "Monthly Vitamins",
"ItemId": "2",
"ItemName": "Vitamin D3",
"SKU": "VIT-D3",
"Quantity": "1",
"ProductCategories": ["Supplements"]
}

Customer Profile Data

Every customer in Vrio automatically syncs to Klaviyo with:

  • Email: Primary identifier
  • First Name & Last Name: For personalization
  • Phone Number: Automatically formatted with country codes (+1 for US/CA)
  • CLV: Customer lifetime value
  • Next Charge Date: Next subscription renewal date
  • ActiveSubscriber: True/false based on subscription status
  • Custom Properties: All tracking fields (tracking1-20) from orders

Technical Details

Smart Deduplication

Vrio uses unique event IDs to prevent duplicate events:

  • Transaction events: transaction_id
  • Product events: transaction_id_product_id
  • Subscription events: transaction_id_product_id_sub

This ensures Klaviyo metrics stay accurate even if events are replayed.

Phone Number Formatting

Vrio automatically handles phone number formatting to ensure compatibility with Klaviyo's requirements:

  • US and Canada: Phone numbers are automatically formatted with +1 country code
  • International: Phone numbers are passed as-is from your order data
  • SMS Compliance: Properly formatted numbers enable Klaviyo's SMS features
  • Profile Field: Phone numbers are sent in the $phone_number profile property

Example formatting:

  • Input: (555) 123-4567 → Output: +15551234567
  • Input: 555.123.4567 → Output: +15551234567
  • Input: +44 20 7946 0958 → Output: +442079460958

Validation & Retry Logic:
If Klaviyo rejects a phone number due to validation errors, Vrio automatically:

  1. Removes the phone number from the profile data
  2. Immediately retries the event without the phone number
  3. Ensures your event data is captured even if phone validation fails

This automatic retry mechanism ensures your customer data and events are never lost due to phone number formatting issues, while still attempting to provide phone numbers when they're valid.

Where to See Results

Customer Profile and Event Timeline in Klaviyo

All Vrio customer data appears in Klaviyo profiles:

Vrio Webhooks Tab

On the customer screen, see exactly what was sent to Klaviyo:

Troubleshooting Common Issues

🔴 Events Not Appearing in Klaviyo

Check These:

  • "Push Events" is enabled in connection settings
  • Private API Key has proper permissions (Events, Lists, Profiles)
  • Connection is marked "Active"
  • Customer has valid email address
  • Campaign filtering isn't excluding the customer

🔴 "Invalid API Key" Errors

The Problem: Can't connect to Klaviyo

The Fix:

  • Verify Private API Key is copied correctly from Klaviyo
  • Check key has Read/Write access for required scopes
  • Ensure you're not using Public key in Private key field

🏥 Need Help?

Check connection logs in Vrio:

  1. Go to the customer screen
  2. Click the "Webhooks" tab to see Klaviyo API calls
  3. Look for error messages in responses
  4. Each request shows exact data sent and received

For API key issues, check your Klaviyo account settings or contact Klaviyo support.

Updated 21 days ago