Klaviyo Helpdesk Export

A Next.js web application that allows non-technical users to easily export helpdesk ticket data from Klaviyo to CSV format.

Features

• Simple, user-friendly interface
• Export closed tickets with performance metrics
• Calculates time-to-close for each ticket
• Supports multiple time periods (Last 24 Hours, Last Week, Last Month)
• Secure - API keys are never stored
• Handles pagination automatically for large datasets

Getting Started

Prerequisites

• Node.js 18+ installed
• A Klaviyo account with API access
• Metric IDs for "Ticket Created" and "Ticket Closed" events

Installation

1. Install dependencies:

npm install

2. Run the development server:

npm run dev

3. Open http://localhost:3000 in your browser

Building for Production

npm run build
npm start

How to Use

Finding Your Klaviyo Private API Key

1. Log in to your Klaviyo account
2. Go to Settings → API Keys
3. Create a new private API key or use an existing one
4. Copy the key (it starts with pk_)

Finding Your Metric IDs

1. In Klaviyo, go to Analytics → Metrics
2. Search for "Ticket Created" metric
3. Click on the metric
4. Copy the metric ID from the URL (format: metric_id_xxxxx)
5. Repeat for "Ticket Closed" metric

Exporting Data

1. Enter your Klaviyo Private API Key
2. Enter the Metric ID for "Ticket Created"
3. Enter the Metric ID for "Ticket Closed"
4. Select your desired time period:
   • Last 24 Hours
   • Last Week
   • Last Month
5. Click "Export to CSV"
6. The CSV file will automatically download

CSV Output Format

The exported CSV includes one row for each event, with dynamic columns based on the event properties.

Standard Columns (always included):

• Event ID: Klaviyo event ID
• Event Type: Either "Ticket Created" or "Ticket Closed"
• Event Date Time: Timestamp when the event occurred
• Ticket ID: Unique identifier for the ticket

Dynamic Columns:

All event properties from your Klaviyo events are automatically included as additional columns. The CSV will contain a column for every unique property found across all events.

Example CSV Output

Event ID,Event Type,Event Date Time,Ticket ID,customer_email,customer_name,priority,subject,ticket_id
"evt_abc123","Ticket Created","2025-11-28T10:30:00.000Z","12345","[email protected]","John Doe","high","Login issue","12345"
"evt_def456","Ticket Closed","2025-11-28T14:45:00.000Z","12345","[email protected]","John Doe","high","Login issue","12345"
"evt_ghi789","Ticket Created","2025-11-28T11:00:00.000Z","12346","[email protected]","Jane Smith","normal","Billing question","12346"
"evt_jkl012","Ticket Closed","2025-11-28T12:30:00.000Z","12346","[email protected]","Jane Smith","normal","Billing question","12346"

Note: The CSV is sorted by Ticket ID, with "Ticket Created" events appearing before "Ticket Closed" events for the same ticket. Empty cells indicate properties that don't exist on that particular event.

For detailed information about the CSV format, including how to analyze the data, see CSV_FORMAT.md.

Technical Details

How It Works

1. The application makes API calls to Klaviyo's get_events endpoint
2. It fetches all events for both "Ticket Created" and "Ticket Closed" metrics within the specified time period
3. Each event is added as a separate row in the CSV
4. Results are sorted by Ticket ID, with "Ticket Created" events appearing before "Ticket Closed" events for the same ticket

API Integration

• Uses Klaviyo API v2024-10-15
• Implements automatic pagination to fetch all events
• Filters events by metric ID and date range
• Handles rate limiting gracefully

Security

• API keys are only used for the request and never stored
• All API calls are made server-side to protect credentials
• No data is persisted or logged

Troubleshooting

"Klaviyo API error: 401"

• Check that your API key is correct and has the necessary permissions
• Ensure the API key has not expired

"Klaviyo API error: 404"

• Verify that your metric IDs are correct
• Make sure you're using the metric IDs, not metric names

No events in export

• Verify that you have ticket events within the selected time period
• Check that the ticket ID field exists in the event properties
• Ensure both metrics are properly configured in Klaviyo

Export taking a long time

• Large time periods with many events will take longer to process
• The app fetches all events before generating the CSV
• Consider using a shorter time period for faster exports

Debugging and Logs

The application includes comprehensive logging to help verify that API calls are working:

• Server logs (terminal): Shows all Klaviyo API calls, responses, and data processing
• Client logs (browser console): Shows export initiation and completion

See TESTING.md for detailed instructions on how to verify the API calls are working.

Development

Project Structure

helpdesk-export/
├── app/
│   ├── api/
│   │   └── export/
│   │       └── route.ts       # API endpoint for fetching and processing data
│   ├── globals.css            # Global styles
│   ├── layout.tsx             # Root layout
│   └── page.tsx               # Main UI component
├── public/                    # Static assets
├── package.json              # Dependencies
└── tsconfig.json             # TypeScript configuration

Key Technologies

• Next.js 15 (App Router)
• TypeScript
• Tailwind CSS
• Klaviyo Events API

License

MIT