openclaw-workspace/skills/api-gateway/references/klaviyo.md

Klaviyo Routing Reference

App name: klaviyo Base URL proxied: a.klaviyo.com

API Path Pattern

/klaviyo/api/{resource}

API Versioning

Include the revision header in all requests:

revision: 2024-10-15

Common Endpoints

Get Profiles

GET /klaviyo/api/profiles

Query parameters:

• filter - Filter profiles (e.g., filter=equals(email,"test@example.com"))
• fields[profile] - Comma-separated list of fields to include
• page[size] - Number of results per page (max 100)

Get a Profile

GET /klaviyo/api/profiles/{profile_id}

Create a Profile

POST /klaviyo/api/profiles
Content-Type: application/json

{
  "data": {
    "type": "profile",
    "attributes": {
      "email": "newuser@example.com",
      "first_name": "John",
      "last_name": "Doe"
    }
  }
}

Update a Profile

PATCH /klaviyo/api/profiles/{profile_id}
Content-Type: application/json

{
  "data": {
    "type": "profile",
    "id": "PROFILE_ID",
    "attributes": {
      "first_name": "Jane"
    }
  }
}

Get Lists

GET /klaviyo/api/lists

Create a List

POST /klaviyo/api/lists
Content-Type: application/json

{
  "data": {
    "type": "list",
    "attributes": {
      "name": "VIP Customers"
    }
  }
}

Add Profiles to List

POST /klaviyo/api/lists/{list_id}/relationships/profiles
Content-Type: application/json

{
  "data": [
    {"type": "profile", "id": "PROFILE_ID"}
  ]
}

Get Segments

GET /klaviyo/api/segments

Get Campaigns

GET /klaviyo/api/campaigns

Create a Campaign

POST /klaviyo/api/campaigns
Content-Type: application/json

{
  "data": {
    "type": "campaign",
    "attributes": {
      "name": "Summer Newsletter",
      "audiences": {
        "included": ["LIST_ID"]
      }
    }
  }
}

Get Flows

GET /klaviyo/api/flows

Update Flow Status

PATCH /klaviyo/api/flows/{flow_id}
Content-Type: application/json

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

Create an Event

POST /klaviyo/api/events
Content-Type: application/json

{
  "data": {
    "type": "event",
    "attributes": {
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "email": "customer@example.com"
          }
        }
      },
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": "Viewed Product"
          }
        }
      },
      "properties": {
        "product_id": "SKU123",
        "product_name": "Blue T-Shirt"
      }
    }
  }
}

Get Metrics

GET /klaviyo/api/metrics

Get Templates

GET /klaviyo/api/templates

Create Webhook

POST /klaviyo/api/webhooks
Content-Type: application/json

{
  "data": {
    "type": "webhook",
    "attributes": {
      "name": "Order Placed Webhook",
      "endpoint_url": "https://example.com/webhooks/klaviyo",
      "enabled": true
    },
    "relationships": {
      "webhook-topics": {
        "data": [
          {"type": "webhook-topic", "id": "campaign:sent"}
        ]
      }
    }
  }
}

Delete Webhook

DELETE /klaviyo/api/webhooks/{webhook_id}

Notes

• All requests use JSON:API specification
• Timestamps are in ISO 8601 RFC 3339 format
• Resource IDs are strings (often base64-encoded)
• Use sparse fieldsets to optimize response size (e.g., fields[profile]=email,first_name)
• Include revision header for API versioning
• Use cursor-based pagination with page[cursor] parameter

Resources

• Klaviyo API Documentation
• API Reference
• Klaviyo Developer Portal