klaviyo

What this skill does

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name KLAVIYO_TOKEN` or `zero doctor check-connector --url https://a.klaviyo.com/api/accounts --method GET`

## Authentication

All requests require three headers:

```
Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN
revision: 2026-04-15
accept: application/vnd.api+json
```

For write requests, also include `content-type: application/vnd.api+json`.

The `revision` header pins the API version. Bump to a newer date only when you need a new feature — older revisions stay supported.

## Environment Variables

| Variable | Description |
|---|---|
| `KLAVIYO_TOKEN` | Klaviyo private API key (format: `pk_...`, 37 chars) |

## Key Endpoints

Base URL: `https://a.klaviyo.com`

All payloads follow the JSON:API spec — the body is always wrapped in `{"data": {"type": "...", "attributes": {...}}}`.

### Accounts

#### Get Account (sanity check)

```bash
curl -s "https://a.klaviyo.com/api/accounts" --header "Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN" --header "revision: 2026-04-15" --header "accept: application/vnd.api+json"
```

### Profiles

#### Get Profiles (paginated)

```bash
curl -s "https://a.klaviyo.com/api/profiles?page[size]=20" --header "Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN" --header "revision: 2026-04-15" --header "accept: application/vnd.api+json"
```

Useful filters (pass via `filter=` query string, URL-encoded):

- `equals(email,"[email protected]")`
- `equals(phone_number,"+15551234567")`
- `greater-than(created,2026-01-01T00:00:00Z)`

#### Get Profile by ID

```bash
curl -s "https://a.klaviyo.com/api/profiles/<your-profile-id>" --header "Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN" --header "revision: 2026-04-15" --header "accept: application/vnd.api+json"
```

#### Create Profile

Write to `/tmp/klaviyo_request.json`:

```json
{
  "data": {
    "type": "profile",
    "attributes": {
      "email": "<your-recipient-email>",
      "phone_number": "<your-phone-e164>",
      "first_name": "<your-first-name>",
      "last_name": "<your-last-name>",
      "properties": {
        "plan": "pro"
      }
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://a.klaviyo.com/api/profiles" --header "Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN" --header "revision: 2026-04-15" --header "accept: application/vnd.api+json" --header "content-type: application/vnd.api+json" -d @/tmp/klaviyo_request.json
```

Returns `201 Created` with the new profile ID. A `409 Conflict` means a profile with that email already exists — use the returned ID to PATCH instead.

#### Update Profile

Replace `<your-profile-id>` with the real ID.

Write to `/tmp/klaviyo_request.json`:

```json
{
  "data": {
    "type": "profile",
    "id": "<your-profile-id>",
    "attributes": {
      "first_name": "<your-new-first-name>",
      "properties": {
        "last_purchase_total": 129.99
      }
    }
  }
}
```

Then run:

```bash
curl -s -X PATCH "https://a.klaviyo.com/api/profiles/<your-profile-id>" --header "Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN" --header "revision: 2026-04-15" --header "accept: application/vnd.api+json" --header "content-type: application/vnd.api+json" -d @/tmp/klaviyo_request.json
```

### Events (server-side tracking)

#### Create Event

Fires a metric event that can trigger flows. The `metric` is auto-created on first use.

Write to `/tmp/klaviyo_request.json`:

```json
{
  "data": {
    "type": "event",
    "attributes": {
      "metric": {
        "data": {
          "type": "metric",
          "attributes": { "name": "Placed Order" }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": { "email": "<your-recipient-email>" }
        }
      },
      "properties": {
        "OrderId": "<your-order-id>",
        "Items": ["SKU-1", "SKU-2"]
      },
      "value": 129.99,
      "time": "2026-04-18T10:00:00Z"
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://a.klaviyo.com/api/events" --header "Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN" --header "revision: 2026-04-15" --header "accept: application/vnd.api+json" --header "content-type: application/vnd.api+json" -d @/tmp/klaviyo_request.json
```

Returns `202 Accepted` — the event is queued. If the profile does not exist, Klaviyo creates it from the supplied identifier.

### Lists

#### Get Lists

```bash
curl -s "https://a.klaviyo.com/api/lists" --header "Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN" --header "revision: 2026-04-15" --header "accept: application/vnd.api+json"
```

#### Create List

Write to `/tmp/klaviyo_request.json`:

```json
{
  "data": {
    "type": "list",
    "attributes": {
      "name": "<your-list-name>"
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://a.klaviyo.com/api/lists" --header "Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN" --header "revision: 2026-04-15" --header "accept: application/vnd.api+json" --header "content-type: application/vnd.api+json" -d @/tmp/klaviyo_request.json
```

#### Add Profiles to a List (no consent change)

Use this to silently add already-known profiles to a list. Replace `<your-list-id>` in both the URL and the body.

Write to `/tmp/klaviyo_request.json`:

```json
{
  "data": [
    { "type": "profile", "id": "<your-profile-id-1>" },
    { "type": "profile", "id": "<your-profile-id-2>" }
  ]
}
```

Then run:

```bash
curl -s -X POST "https://a.klaviyo.com/api/lists/<your-list-id>/relationships/profiles" --header "Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN" --header "revision: 2026-04-15" --header "accept: application/vnd.api+json" --header "content-type: application/vnd.api+json" -d @/tmp/klaviyo_request.json
```

### Subscriptions

#### Subscribe Profiles (with consent)

Use this when you have explicit consent — this is the endpoint that flips marketing-opt-in to `SUBSCRIBED` and can add the profile to a list. Replace `<your-list-id>`.

Write to `/tmp/klaviyo_request.json`:

```json
{
  "data": {
    "type": "profile-subscription-bulk-create-job",
    "attributes": {
      "custom_source": "Marketing Event",
      "profiles": {
        "data": [
          {
            "type": "profile",
            "attributes": {
              "email": "<your-recipient-email>",
              "subscriptions": {
                "email": {
                  "marketing": { "consent": "SUBSCRIBED" }
                }
              }
            }
          }
        ]
      }
    },
    "relationships": {
      "list": {
        "data": { "type": "list", "id": "<your-list-id>" }
      }
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://a.klaviyo.com/api/profile-subscription-bulk-create-jobs" --header "Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN" --header "revision: 2026-04-15" --header "accept: application/vnd.api+json" --header "content-type: application/vnd.api+json" -d @/tmp/klaviyo_request.json
```

Returns `202 Accepted`. Max 1000 profiles per job. Requires scopes `lists:write`, `profiles:write`, `subscriptions:write`.

### Metrics

#### Get Metrics

```bash
curl -s "https://a.klaviyo.com/api/metrics" --header "Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN" --header "revision: 2026-04-15" --header "accept: application/vnd.api+json"
```

#### Query Metric Aggregates

Replace `<your-metric-id>`. Write to `/tmp/klaviyo_request.json`:

```json
{
  "data": {
    "type": "metric-aggregate",
    "attributes": {
      "metric_id": "<your-metric-id>",
      "measurements": ["count", "sum_value"],
      "interval": "day",
      "filter": [
        "greater-or-equal(datetime,2026-04-01T00:00:00Z)",
        "less-than(datetime,2026-05-01T00:00:00Z)"
      ]
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://a.klaviyo.com/api/metric-aggregates" --header "Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN" --header "revision: 2026-04-15" --header "accept: application/vnd.api+json" --header "content-type: application/vnd.api+json" -d @/tmp/klaviyo_request.json
```

### Segments

#### Get S