Skip to content

thatrebeccarae/claude-marketing / skills/klaviyo-developer

klaviyo-developer

Flagged

Klaviyo API and developer integration expertise. Event tracking, SDKs, webhooks, rate limits, OAuth, catalog sync, and code patterns. Use when the user asks about Klaviyo API, integrating with Klaviyo, tracking events, building custom integrations, webhook handling, or developer implementation. For marketing strategy, flow optimization, and campaign auditing, see the klaviyo-analyst skill.

FileKindSize
.env.exampleother968 B
EXAMPLES.mdmarkdown15.4 KB
LICENSEother1.0 KB
REFERENCE.mdmarkdown41.1 KB
SKILL.mdskill md19.3 KB
requirements.txtmanifest143 B
scripts/dev_tools.pyscript22.8 KB
scripts/klaviyo_client.pyscript21.5 KB

scripts/klaviyo_client.py

View on GitHub
#!/usr/bin/env python3
"""
Klaviyo Developer API Client

Read-write SDK wrapper for Klaviyo event tracking, profile management,
bulk imports, catalog sync, and data export.

Usage:
    python klaviyo_client.py --action track-event --email user@example.com --event "Placed Order" --properties '{"value": 99.99}'
    python klaviyo_client.py --action upsert-profile --email user@example.com --properties '{"first_name": "Jane"}'
    python klaviyo_client.py --action bulk-import --file contacts.csv --list-id LIST_ID
    python klaviyo_client.py --action catalog-items --format table
    python klaviyo_client.py --action export-profiles --max-pages 5 --output profiles.csv

Environment Variables:
    KLAVIYO_API_KEY: Klaviyo private API key (required, starts with "pk_")
"""

import os
import sys
import json
import csv
import argparse
import traceback
from typing import Dict, List, Optional

try:
    from klaviyo_api import KlaviyoAPI
    from dotenv import load_dotenv
except ImportError:
    print("Error: Required packages not installed.", file=sys.stderr)
    print("Install with: pip install klaviyo-api python-dotenv", file=sys.stderr)
    sys.exit(1)


def _safe_output_path(path: str) -> str:
    """Validate output path does not escape working directory."""
    resolved = os.path.realpath(path)
    cwd = os.path.realpath(os.getcwd())
    if not resolved.startswith(cwd + os.sep) and resolved != cwd:
        raise ValueError(f"Output path must be within working directory: {cwd}")
    return resolved


def _safe_input_file(path: str) -> str:
    """Validate input file path: must be .csv and exist."""
    resolved = os.path.realpath(path)
    if not os.path.exists(resolved):
        raise FileNotFoundError(f"File not found: {path}")
    if not resolved.lower().endswith(".csv"):
        raise ValueError("Input file must be a .csv file")
    return resolved


class KlaviyoDevClient:
    """Read-write client for Klaviyo developer operations."""

    API_REVISION = "2025-10-15"

    def __init__(self):
        """Initialize the client with credentials from environment."""
        load_dotenv()

        api_key = os.environ.get("KLAVIYO_API_KEY")
        if not api_key:
            raise ValueError(
                "KLAVIYO_API_KEY environment variable not set. "
                "Find your API key in Klaviyo: Settings > Account > API Keys"
            )

        if not api_key.startswith("pk_"):
            raise ValueError(
                "KLAVIYO_API_KEY should start with 'pk_'. "
                "Use a Private API Key, not a Public API Key."
            )

        try:
            self.client = KlaviyoAPI(api_key, max_delay=60, max_retries=3)
        except Exception as e:
            print(f"  caused by: {type(e).__name__}: {e}", file=sys.stderr)
            raise RuntimeError("Failed to initialize Klaviyo client. Check your API key.") from e

    def track_event(
        self,
        event_name: str,
        email: str,
        properties: Optional[Dict] = None,
        unique_id: Optional[str] = None,
    ) -> Dict:
        """
        Track a custom event.

        Args:
            event_name: Name of the event (e.g., "Placed Order")
            email: Profile email address
            properties: Event properties dict
            unique_id: Idempotency key to prevent duplicates

        Returns:
            API response dictionary
        """
        body = self._build_event_body(event_name, email, properties, unique_id)

        try:
            response = self.client.Events.create_event(body)
            return {"status": "success", "event": event_name, "email": email}
        except Exception as e:
            print(f"  caused by: {type(e).__name__}: {e}", file=sys.stderr)
            raise RuntimeError("Failed to track event. Check your API key and event data.") from e

    def upsert_profile(
        self,
        email: Optional[str] = None,
        phone: Optional[str] = None,
        properties: Optional[Dict] = None,
    ) -> Dict:
        """
        Create or update a profile.

        Args:
            email: Profile email address
            phone: Profile phone number (with country code)
            properties: Custom profile properties

        Returns:
            API response with profile data
        """
        body = self._build_profile_body(email, phone, properties)

        try:
            response = self.client.Profiles.create_profile(body)
            return self._parse_jsonapi_response(response)
        except Exception as e:
            print(f"  caused by: {type(e).__name__}: {e}", file=sys.stderr)
            raise RuntimeError("Failed to upsert profile. Check your API key and profile data.") from e

    def bulk_import(
        self, profiles: List[Dict], list_id: Optional[str] = None
    ) -> Dict:
        """
        Submit a bulk profile import job (max 10,000 profiles per job).

        Args:
            profiles: List of profile dicts with email, phone, and/or properties
            list_id: Optional list ID to add profiles to

        Returns:
            Dictionary with job ID and status
        """
        if len(profiles) > 10000:
            raise ValueError("Bulk import limited to 10,000 profiles per job")

        profile_data = []
        for p in profiles:
            attrs = {}
            if p.get("email"):
                attrs["email"] = p["email"]
            if p.get("phone"):
                attrs["phone_number"] = p["phone"]
            if p.get("first_name"):
                attrs["first_name"] = p["first_name"]
            if p.get("last_name"):
                attrs["last_name"] = p["last_name"]

            # Custom properties
            custom_props = {
                k: v
                for k, v in p.items()
                if k not in ("email", "phone", "first_name", "last_name")
            }
            if custom_props:
                attrs["properties"] = custom_props

            profile_data.append({"type": "profile", "attributes": attrs})

        body = {
            "data": {
                "type": "profile-bulk-import-job",
                "attributes": {"profiles": {"data": profile_data}},
            }
        }

        if list_id:
            body["data"]["relationships"] = {
                "lists": {"data": [{"type": "list", "id": list_id}]}
            }

        try:
            response = self.client.Profiles.spawn_bulk_profile_import_job(body)
            result = self._parse_jsonapi_response(response)
            return {
                "status": "submitted",
                "job_id": result.get("id") if isinstance(result, dict) else None,
                "profiles_submitted": len(profiles),
            }
        except Exception as e:
            print(f"  caused by: {type(e).__name__}: {e}", file=sys.stderr)
            raise RuntimeError("Failed to submit bulk import. Check your API key and profile data.") from e

    def get_import_job_status(self, job_id: str) -> Dict:
        """
        Check status of a bulk import job.

        Args:
            job_id: The import job ID

        Returns:
            Dictionary with job status and progress
        """
        try:
            response = self.client.Profiles.get_bulk_profile_import_job(job_id)
            return self._parse_jsonapi_response(response)
        except Exception as e:
            print(f"  caused by: {type(e).__name__}: {e}", file=sys.stderr)
            raise RuntimeError("Failed to get import job status. Check job ID and API key.") from e

    def get_catalog_items(self, filter_str: Optional[str] = None) -> List[Dict]:
        """
        List catalog items.

        Args:
            filter_str: Optional filter expression

        Returns:
            List of catalog item dictionaries
        """
        try:
            kwargs = {}
            if filter_str:
                kwargs["filter"] = filter_str

            response = self.client.Catalogs.get_catalog_items(**kwargs)
            return self._parse_jsonapi_response(response)
        except Exception as e:
            print(f"  caused by: {type(e).__name__}: {e}", file=sys.stderr)
            raise RuntimeError("Failed to fetch catalog items. Check your API key and catalog scopes.") from e

    def create_catalog_item(self, item_data: Dict) -> Dict:
        """
        Create a catalog item.

        Args:
            item_data: Dictionary with title, description, url, image_url, price, etc.

        Returns:
            Created catalog item data
        """
        body = {
            "data": {
                "type": "catalog-item",
                "attributes": {
                    "external_id": item_data.get("external_id", item_data.get("id")),
                    "title": item_data.get("title"),
                    "description": item_data.get("description", ""),
                    "url": item_data.get("url", ""),
                    "image_full_url": item_data.get("image_url", ""),
                    "custom_metadata": {
                        k: v
                        for k, v in item_data.items()
                        if k
                        not in (
                            "external_id",
                            "id",
                            "title",
                            "description",
                            "url",
                            "image_url",
                            "price",
                        )
                    },
                },
            }
        }

        if item_data.get("price"):
            body["data"]["attributes"]["price"] = float(item_data["price"])

        try:
            response = self.client.Catalogs.create_catalog_item(body)
            return self._parse_jsonapi_response(response)
        except Exception as e:
            print(f"  caused by: {type(e).__name__}: {e}", file=sys.stderr)
            raise RuntimeError("Failed to create catalog item. Check your API key and item data.") from e

    def export_profiles(
        self, page_size: int = 100, max_pages: Optional[int] = None
    ) -> List[Dict]:
        """
        Export profiles with cursor-based pagination.

        Args:
            page_size: Number of profiles per page (max 100)
            max_pages: Maximum pages to fetch (None for all)

        Returns:
            List of profile dictionaries
        """
        profiles = []
        cursor = None
        page_count = 0

        while True:
            try:
                kwargs = {"page_size": min(page_size, 100)}
                if cursor:
                    kwargs["page_cursor"] = cursor

                response = self.client.Profiles.get_profiles(**kwargs)

                if hasattr(response, "to_dict"):
                    response = response.to_dict()
                elif isinstance(response, str):
                    response = json.loads(response)

                data = response.get("data", [])
                for item in data:
                    flat = {"id": item.get("id")}
                    attrs = item.get("attributes", {})
                    flat.update(attrs)
                    profiles.append(flat)

                page_count += 1
                print(
                    f"Page {page_count}: fetched {len(data)} profiles "
                    f"(total: {len(profiles)})",
                    file=sys.stderr,
                )

                # Check pagination
                next_link = response.get("links", {}).get("next")
                if not next_link:
                    break

                if max_pages and page_count >= max_pages:
                    print(
                        f"Reached max pages limit ({max_pages})", file=sys.stderr
                    )
                    break

                # Extract cursor from next link
                from urllib.parse import urlparse, parse_qs

                parsed = urlparse(next_link)
                cursor = parse_qs(parsed.query).get("page[cursor]", [None])[0]

                if not cursor:
                    break

            except Exception as e:
                print(f"  caused by: {type(e).__name__}: {e}", file=sys.stderr)
                raise RuntimeError(
                    "Failed to export profiles. Check your API key and profile scopes."
                ) from e

        return profiles

    def get_metrics(self) -> List[Dict]:
        """
        List all available event types (metrics).

        Returns:
            List of metric dictionaries with id and name
        """
        try:
            response = self.client.Metrics.get_metrics()
            return self._parse_jsonapi_response(response)
        except Exception as e:
            print(f"  caused by: {type(e).__name__}: {e}", file=sys.stderr)
            raise RuntimeError("Failed to fetch metrics. Check your API key and metrics scopes.") from e

    def _parse_jsonapi_response(self, response) -> List[Dict]:
        """Flatten JSON:API envelope into simple dictionaries."""
        if hasattr(response, "to_dict"):
            response = response.to_dict()
        elif isinstance(response, str):
            response = json.loads(response)

        data = response.get("data", response)

        if isinstance(data, list):
            return [self._flatten_resource(item) for item in data]
        elif isinstance(data, dict):
            return self._flatten_resource(data)
        else:
            return data

    def _flatten_resource(self, resource: Dict) -> Dict:
        """Flatten a single JSON:API resource object."""
        flat = {
            "id": resource.get("id"),
            "type": resource.get("type"),
        }

        attributes = resource.get("attributes", {})
        if attributes:
            flat.update(attributes)

        return flat

    def _build_event_body(
        self,
        event_name: str,
        email: str,
        properties: Optional[Dict] = None,
        unique_id: Optional[str] = None,
    ) -> Dict:
        """Build JSON:API event body."""
        body = {
            "data": {
                "type": "event",
                "attributes": {
                    "metric": {
                        "data": {
                            "type": "metric",
                            "attributes": {"name": event_name},
                        }
                    },
                    "profile": {
                        "data": {
                            "type": "profile",
                            "attributes": {"email": email},
                        }
                    },
                    "properties": properties or {},
                },
            }
        }

        if unique_id:
            body["data"]["attributes"]["unique_id"] = unique_id

        return body

    def _build_profile_body(
        self,
        email: Optional[str] = None,
        phone: Optional[str] = None,
        properties: Optional[Dict] = None,
    ) -> Dict:
        """Build JSON:API profile body."""
        attrs = {}
        if email:
            attrs["email"] = email
        if phone:
            attrs["phone_number"] = phone

        if properties:
            # Separate standard fields from custom properties
            standard_fields = {
                "first_name",
                "last_name",
                "organization",
                "title",
                "image",
                "location",
            }
            for key in list(properties.keys()):
                if key in standard_fields:
                    attrs[key] = properties.pop(key)

            if properties:
                attrs["properties"] = properties

        return {"data": {"type": "profile", "attributes": attrs}}


def main():
    parser = argparse.ArgumentParser(
        description="Klaviyo developer operations client",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  # Track a custom event
  python klaviyo_client.py --action track-event \\
      --email user@example.com --event "Placed Order" \\
      --properties '{"value": 99.99, "OrderId": "ORD-123"}'

  # Upsert a profile
  python klaviyo_client.py --action upsert-profile \\
      --email user@example.com \\
      --properties '{"first_name": "Jane", "loyalty_tier": "Gold"}'

  # Check import job status
  python klaviyo_client.py --action import-status --job-id JOB_ID

  # List catalog items
  python klaviyo_client.py --action catalog-items --format table

  # Export profiles to CSV
  python klaviyo_client.py --action export-profiles \\
      --max-pages 10 --format csv --output profiles.csv

  # List available metrics
  python klaviyo_client.py --action metrics
        """,
    )

    parser.add_argument(
        "--action",
        required=True,
        choices=[
            "track-event",
            "upsert-profile",
            "bulk-import",
            "import-status",
            "catalog-items",
            "create-catalog-item",
            "export-profiles",
            "metrics",
        ],
        help="Action to perform",
    )
    parser.add_argument("--email", help="Profile email address")
    parser.add_argument("--event", help="Event name (for track-event)")
    parser.add_argument(
        "--properties", help="JSON properties string (for events or profiles)"
    )
    parser.add_argument("--file", help="CSV file path (for bulk-import)")
    parser.add_argument("--list-id", help="List ID (for bulk-import)")
    parser.add_argument("--job-id", help="Import job ID (for import-status)")
    parser.add_argument(
        "--max-pages",
        type=int,
        help="Max pages to fetch (for export-profiles)",
    )
    parser.add_argument(
        "--format",
        choices=["json", "table", "csv"],
        default="json",
        help="Output format (default: json)",
    )
    parser.add_argument("--output", help="Output file path (default: stdout)")
    parser.add_argument(
        "--debug",
        action="store_true",
        help="Re-raise exceptions with full traceback instead of friendly error",
    )

    args = parser.parse_args()

    try:
        client = KlaviyoDevClient()

        # Parse properties
        properties = None
        if args.properties:
            properties = json.loads(args.properties)

        # Execute action
        if args.action == "track-event":
            if not args.email:
                parser.error("--email is required for track-event")
            if not args.event:
                parser.error("--event is required for track-event")
            result = client.track_event(
                event_name=args.event,
                email=args.email,
                properties=properties,
            )

        elif args.action == "upsert-profile":
            if not args.email:
                parser.error("--email is required for upsert-profile")
            result = client.upsert_profile(
                email=args.email, properties=properties
            )

        elif args.action == "bulk-import":
            if not args.file:
                parser.error("--file is required for bulk-import")
            # Read CSV
            profiles = []
            safe_file = _safe_input_file(args.file)
            with open(safe_file, "r", encoding="utf-8") as f:
                reader = csv.DictReader(f)
                for row in reader:
                    profiles.append(dict(row))
            result = client.bulk_import(profiles, list_id=args.list_id)

        elif args.action == "import-status":
            if not args.job_id:
                parser.error("--job-id is required for import-status")
            result = client.get_import_job_status(args.job_id)

        elif args.action == "catalog-items":
            result = client.get_catalog_items()

        elif args.action == "create-catalog-item":
            if not properties:
                parser.error(
                    "--properties is required for create-catalog-item (JSON with title, etc.)"
                )
            result = client.create_catalog_item(properties)

        elif args.action == "export-profiles":
            result = client.export_profiles(max_pages=args.max_pages)

        elif args.action == "metrics":
            result = client.get_metrics()

        # Format output
        if args.format == "csv" and isinstance(result, list):
            output = format_as_csv(result)
        elif args.format == "json":
            output = json.dumps(result, indent=2, default=str)
        else:
            output = json.dumps(result, indent=2, default=str)

        # Write output
        if args.output:
            safe_path = _safe_output_path(args.output)
            with open(safe_path, "w", encoding="utf-8") as f:
                f.write(output)
            print(f"Data saved to {args.output}", file=sys.stderr)
        else:
            print(output)

    except (ValueError, FileNotFoundError) as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)
    except Exception:
        if args.debug:
            traceback.print_exc()
        else:
            print("Error: Operation failed. Check your API key and network connection.", file=sys.stderr)
        sys.exit(1)


def format_as_csv(data: List[Dict]) -> str:
    """Format list of dicts as CSV string."""
    if not data:
        return ""

    import io

    output = io.StringIO()
    # Collect all keys across all rows
    all_keys = []
    for row in data:
        for key in row.keys():
            if key not in all_keys:
                all_keys.append(key)

    writer = csv.DictWriter(output, fieldnames=all_keys, extrasaction="ignore")
    writer.writeheader()
    for row in data:
        # Stringify nested dicts/lists
        clean_row = {}
        for k, v in row.items():
            if isinstance(v, (dict, list)):
                clean_row[k] = json.dumps(v)
            else:
                clean_row[k] = v
        writer.writerow(clean_row)

    return output.getvalue()


if __name__ == "__main__":
    main()
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall