hvac-marketing-skills/tools/integrations/klaviyo.md

Klaviyo

E-commerce email and SMS marketing platform with profiles, flows, campaigns, segments, and event tracking.

Capabilities

Integration	Available	Notes
API	✓	REST API with JSON:API spec, revision-versioned
MCP	-	Not available
CLI	✓	klaviyo.js
SDK	✓	Python, Node.js, Ruby, PHP, Java, C#

Authentication

• Type: Private API Key
• Header: Authorization: Klaviyo-API-Key {private_api_key}
• Revision Header: revision: 2024-10-15 (required on all requests)
• Get key: Account Settings > API Keys at https://www.klaviyo.com/settings/account/api-keys
• Note: Private keys are prefixed with pk_; public keys (6-char site ID) are for client-side only

Common Agent Operations

List profiles

GET https://a.klaviyo.com/api/profiles/?page[size]=20

# Filter by email
GET https://a.klaviyo.com/api/profiles/?filter=equals(email,"user@example.com")

Create profile

POST https://a.klaviyo.com/api/profiles/

{
  "data": {
    "type": "profile",
    "attributes": {
      "email": "user@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone_number": "+15551234567"
    }
  }
}

Update profile

PATCH https://a.klaviyo.com/api/profiles/{profileId}/

{
  "data": {
    "type": "profile",
    "id": "{profileId}",
    "attributes": {
      "first_name": "Updated Name"
    }
  }
}

List all lists

GET https://a.klaviyo.com/api/lists/

Create list

POST https://a.klaviyo.com/api/lists/

{
  "data": {
    "type": "list",
    "attributes": {
      "name": "Newsletter Subscribers"
    }
  }
}

Add profiles to list

POST https://a.klaviyo.com/api/lists/{listId}/relationships/profiles/

{
  "data": [
    { "type": "profile", "id": "{profileId1}" },
    { "type": "profile", "id": "{profileId2}" }
  ]
}

Track event

POST https://a.klaviyo.com/api/events/

{
  "data": {
    "type": "event",
    "attributes": {
      "metric": {
        "data": {
          "type": "metric",
          "attributes": { "name": "Placed Order" }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": { "email": "user@example.com" }
        }
      },
      "properties": {
        "value": 99.99,
        "items": ["Product A"]
      },
      "time": "2025-01-15T10:00:00Z"
    }
  }
}

List campaigns

GET https://a.klaviyo.com/api/campaigns/?filter=equals(messages.channel,"email")

List flows

GET https://a.klaviyo.com/api/flows/

Update flow status

PATCH https://a.klaviyo.com/api/flows/{flowId}/

{
  "data": {
    "type": "flow",
    "id": "{flowId}",
    "attributes": {
      "status": "live"
    }
  }
}

List metrics

GET https://a.klaviyo.com/api/metrics/

List segments

GET https://a.klaviyo.com/api/segments/

API Pattern

Klaviyo uses the JSON:API specification. All request/response bodies use { "data": { "type": "...", "attributes": {...} } } format. Relationships are managed via /relationships/ sub-endpoints. The revision header is required on every request and determines API behavior version.

Key Metrics

Profile Fields

• email - Email address
• phone_number - Phone for SMS
• first_name, last_name - Name fields
• properties - Custom properties object
• subscriptions - Email/SMS subscription status

Event Fields

• metric - The metric/event name
• properties - Custom event properties
• time - Event timestamp
• value - Monetary value (for revenue tracking)

Campaign/Flow Metrics

• send_count - Number of sends
• open_rate - Open percentage
• click_rate - Click percentage
• revenue - Attributed revenue

Parameters

Common Query Parameters

• page[size] - Results per page (default 20, max 100)
• page[cursor] - Cursor for pagination
• filter - Filter expressions (e.g., equals(email,"user@example.com"))
• sort - Sort field (prefix - for descending)
• include - Include related resources
• fields[resource] - Sparse fieldsets

When to Use

• E-commerce email/SMS marketing automation
• Syncing customer profiles from external systems
• Tracking purchase events and customer behavior
• Managing email flows and drip campaigns
• Segmenting audiences for targeted campaigns
• Reporting on campaign and flow performance

Rate Limits

• Steady-state: 75 requests/second for most endpoints
• Burst: up to 700 requests in 1 minute
• Rate limit headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
• Lower limits on some write endpoints (profiles, events)

Relevant Skills

• email-sequence
• ecommerce-email
• lifecycle-marketing
• customer-segmentation