Klaviyo-Compatible API Overview

Postscript provides a Klaviyo-compatible API surface that allows you to migrate existing integrations with minimal code changes. This API accepts requests in Klaviyo's format and translates them to Postscript's native data model.

Base URL

Local development:

http://localhost:8020/klaviyo/v1

Production:

https://api.postscript.io/klaviyo/v1

This replaces Klaviyo's https://a.klaviyo.com/api base URL.

Authentication

The Klaviyo-compatible API accepts both authentication formats:

Klaviyo-style header:

Authorization: Klaviyo-API-Key ps_live_your_key_here

Bearer token (also works):

Authorization: Bearer ps_live_your_key_here

Use your Postscript API key in place of your Klaviyo API key.

Available Endpoints

The Klaviyo-compatible API supports:

Endpoint	Description
`POST /api/events`	Create a single event
`POST /api/event-bulk-create-jobs`	Create events in bulk
`POST /api/profiles`	Create a profile
`POST /api/profile-bulk-import-jobs`	Import profiles in bulk

Request Format Differences

Events

Klaviyo events use a nested attributes structure:

{
  "data": {
    "type": "event",
    "attributes": {
      "metric": { "data": { "type": "metric", "attributes": { "name": "Viewed Product" } } },
      "profile": { "data": { "type": "profile", "attributes": { "email": "[email protected]" } } },
      "properties": { "product_id": "123" },
      "time": "2024-01-15T10:30:00Z"
    }
  }
}

Profiles

Klaviyo profiles use external_id for customer identifiers:

{
  "data": {
    "type": "profile",
    "attributes": {
      "email": "[email protected]",
      "external_id": "cust_123",
      "first_name": "Jane",
      "last_name": "Doe",
      "properties": {
        "custom_field": "value"
      }
    }
  }
}

Response Format

Responses follow Klaviyo's JSON:API format:

{
  "data": {
    "type": "event",
    "id": "evt_abc123",
    "attributes": { ... }
  }
}

Rate Limits

The Klaviyo-compatible API shares rate limits with the Native API. See Rate Limiting for details.

Limitations

Some Klaviyo features are not supported:

Catalog endpoints — Use the Native API for product catalog management
Campaign endpoints — Use the Postscript dashboard or Native API
List/segment management — Use the Native API
Metric browsing — Events are mapped to Postscript event types

Next Steps

Migration Guide — Step-by-step migration instructions
Klaviyo-Compatible API Reference — Full endpoint documentation
Native API Reference — Postscript's native API