Migration Guide

This guide walks you through migrating your existing Klaviyo API integration to Postscript.

Overview

Migration involves three steps:

1. Update the base URL — Point requests to Postscript
2. Replace your API key — Use your Postscript key
3. Verify functionality — Test your integration

Step 1: Update Base URL

Replace Klaviyo's base URL with Postscript's Klaviyo-compatible endpoint:

Example (local dev):

- const BASE_URL = 'https://a.klaviyo.com/api';
+ const BASE_URL = 'http://localhost:8020/klaviyo/v1';

Step 2: Replace API Key

Swap your Klaviyo API key for your Postscript API key. The authorization header format remains the same:

- Authorization: Klaviyo-API-Key pk_abc123...
+ Authorization: Klaviyo-API-Key ps_live_abc123...

You can generate API keys in the Postscript dashboard under Settings > API Keys.

Step 3: Verify Functionality

Test Event Tracking

Send a test event and verify it appears in Postscript:

curl -X POST https://a.postscript.io/api/events \
  -H "Authorization: Klaviyo-API-Key ps_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "event",
      "attributes": {
        "metric": {
          "data": {
            "type": "metric",
            "attributes": { "name": "Test Event" }
          }
        },
        "profile": {
          "data": {
            "type": "profile",
            "attributes": { "email": "[email protected]" }
          }
        },
        "properties": { "test": true },
        "time": "2024-01-15T10:30:00Z"
      }
    }
  }'

Test Profile Creation

Create a test profile:

curl -X POST https://a.postscript.io/api/profiles \
  -H "Authorization: Klaviyo-API-Key ps_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "profile",
      "attributes": {
        "email": "[email protected]",
        "first_name": "Test",
        "last_name": "User"
      }
    }
  }'

Common Issues

401 Unauthorized

• Verify your Postscript API key is correct
• Check the key has the required scopes (events:write, profiles:write)

404 Not Found

• Ensure you're using /api (not /api/v1 or other variations)
• Verify the endpoint is supported (see Overview)

400 Bad Request

• The request format should match Klaviyo's format exactly
• Check required fields are present (metric, profile for events)

Gradual Migration

For high-traffic integrations, consider a gradual rollout:

1. Dual-write phase — Send events to both Klaviyo and Postscript
2. Validation phase — Compare data in both systems
3. Cutover — Switch to Postscript only

SDK Updates

If you're using an official Klaviyo SDK, you'll need to either:

• Configure the SDK to use a custom base URL (if supported)
• Switch to direct HTTP calls
• Use Postscript's native SDK (coming soon)

Need Help?

• Review the Klaviyo-Compatible API Reference for endpoint details
• Check the Native API for Postscript-native alternatives
• Contact support at [email protected]