> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavera.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Klaviyo

> 5 production-ready jobs — predictive persona enrichment, flow content refresh, segment overlap analysis, product affinity focus groups, and SMS vs. email creative testing

Klaviyo is your e-commerce marketing brain — predictive analytics, flow automation, segmentation, product catalogs, and multi-channel messaging. These five jobs connect Klaviyo's data to Mavera's surfaces (Custom Personas, Generate, Mave Agent, Focus Groups) so your personas reflect real CLV tiers, your underperforming flows get data-driven rewrites, and your creative decisions are tested before sending.

***

## API Reference Card

| Detail              | Value                                                          |
| ------------------- | -------------------------------------------------------------- |
| **Base URL**        | `https://a.klaviyo.com/api/`                                   |
| **Auth**            | `Klaviyo-API-Key` header (private API key)                     |
| **Rate limits**     | Tiered — 1 to 350 req/sec burst depending on endpoint and plan |
| **Revision header** | Required: `revision: 2024-10-15` (or latest)                   |
| **Mavera base**     | `https://app.mavera.io/api/v1`                                 |
| **Mavera auth**     | `Authorization: Bearer mvra_live_...`                          |

<Info>
  All examples use two environment variables: `KLAVIYO_API_KEY` (your private API key, starts with `pk_`) and `MAVERA_API_KEY`. Klaviyo's API requires a `revision` header on every request — the examples use `2024-10-15`. Python examples use `requests`; JavaScript examples use `fetch`.
</Info>

***

## Prerequisites

<Steps>
  <Step title="Klaviyo account with data">You need an active Klaviyo account with at least 30 days of tracked events, profile data, and predictive analytics enabled (available on Growth+ plans).</Step>
  <Step title="Private API key">Generate a private key in Klaviyo → Settings → API Keys. Grant the key read access to Profiles, Segments, Metrics, Campaigns, and Flows.</Step>
  <Step title="Predictive analytics">Predictive CLV, churn risk, and next purchase date require sufficient order history. Klaviyo needs \~180 days of order data and 500+ customers to generate predictions.</Step>
  <Step title="Mavera API key">Get your key from [Mavera dashboard](https://app.mavera.io/settings/api-keys).</Step>

  <Step title="Environment variables">
    ```bash theme={"dark"}
    export KLAVIYO_API_KEY="pk_xxxxx"
    export MAVERA_API_KEY="mvra_live_xxxxx"
    ```
  </Step>
</Steps>

***

## Jobs

| # | Job                                                                                              | Klaviyo Data                       | Mavera Surface  | Output                                  |
| - | ------------------------------------------------------------------------------------------------ | ---------------------------------- | --------------- | --------------------------------------- |
| 1 | [Predictive Analytics → Persona Enrichment](/integrations/klaviyo/predictive-persona-enrichment) | Profiles with predictive CLV/churn | Custom Personas | CLV-tier personas with churn profiles   |
| 2 | [Flow Performance → Content Refresh](/integrations/klaviyo/flow-content-refresh)                 | Metric aggregates (flow-level)     | Generate        | Rewritten underperforming flow content  |
| 3 | [Segment Overlap Analysis](/integrations/klaviyo/segment-overlap-analysis)                       | Segments + member counts           | Mave Agent      | Simplified segmentation recommendations |
| 4 | [Product Affinity → Focus Group](/integrations/klaviyo/product-affinity-focus-group)             | Catalog + purchase data            | Focus Groups    | Cross-sell validation with Likert + NPS |
| 5 | [SMS vs. Email Creative Testing](/integrations/klaviyo/sms-vs-email-testing)                     | SMS + email campaign performance   | Focus Groups    | Channel preference insights             |

***

## Rate Limits & Production Notes

| Klaviyo API            | Limit                          | Strategy                                       |
| ---------------------- | ------------------------------ | ---------------------------------------------- |
| Profiles GET           | 10-75 req/sec (plan-dependent) | Respect `Retry-After`; paginate with cursors   |
| Segments GET           | 10-15 req/sec                  | Cache segment lists; definitions change rarely |
| Catalog Items          | 10-75 req/sec                  | Cache catalog; changes are event-driven        |
| Metric Aggregates POST | 3-10 req/sec                   | Batch time periods; cache results              |
| Flows GET              | 10-15 req/sec                  | Cache flow structures; metrics are separate    |

<Warning>
  Klaviyo's rate limits are **tiered by plan and endpoint**. The `Retry-After` header on 429 responses gives the exact wait time. Always implement exponential backoff. The revision header (`revision: 2024-10-15`) is mandatory on every request — omitting it returns 400.
</Warning>

**Production checklist:**

| Concern                  | Recommendation                                                                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API key security         | Klaviyo private keys (`pk_`) have full read access. Never expose in client-side code. Use server-side calls only.                                       |
| Revision header          | Pin to a specific revision and test before upgrading. Breaking changes are released per-revision, not silently.                                         |
| Predictive analytics lag | Predictive CLV and churn risk update daily. Don't poll more than once per 24 hours for persona enrichment.                                              |
| Catalog sync             | Catalog data comes from your e-commerce platform integration (Shopify, BigCommerce, etc.). Ensure the sync is active before querying catalog items.     |
| Mavera credits           | Monitor at [Dashboard](https://app.mavera.io/settings/usage). Job 4 (product affinity) with 3 personas × 5 questions × 2 responses is credit-intensive. |
| SMS compliance           | Always respect SMS opt-in preferences. Never send promotional SMS without explicit consent. Klaviyo enforces this at the platform level.                |

***

## What's Next

<CardGroup cols={2}>
  <Card title="All Integrations" icon="plug" href="/integrations">
    50+ API integrations with full code
  </Card>

  <Card title="Klaviyo API Docs" icon="bolt" href="https://developers.klaviyo.com/en/reference/api_overview">
    Official Klaviyo API reference
  </Card>

  <Card title="Personas API" icon="users" href="/api-reference/personas">
    Full reference for POST /api/v1/personas
  </Card>

  <Card title="Focus Groups API" icon="comments" href="/api-reference/focus-groups">
    Full reference for POST /api/v1/focus-groups
  </Card>

  <Card title="Mave Agent" icon="brain" href="/api-reference/mave">
    Full reference for POST /api/v1/mave/chat
  </Card>

  <Card title="Generate API" icon="wand-magic-sparkles" href="/api-reference/generations">
    Full reference for POST /api/v1/generations
  </Card>
</CardGroup>