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

# Klaviyo

> Send Circuly subscription, payment, and invoice events to Klaviyo for email automation, segmentation, and win-back flows.

## Overview

Circuly forwards subscription lifecycle, payment, billing, and invoice events to Klaviyo via the **Events API v3**. Once connected, each event is attached to the matching customer profile in Klaviyo so you can trigger flows, build segments, and run win-back campaigns from real subscription activity.

<Note>
  Basic setup — connecting your API key, sending test events, and installing starter templates and flows — is handled inside Circuly Subscriptions under **Integrations → Klaviyo**. This page is the reference for everything that ships *after* that setup: event properties, advanced flow patterns, and segment prompts you can use with Klaviyo's MCP server.
</Note>

## Events reference

Every event includes the customer profile (email, first name, last name), a Klaviyo metric name, and the event-specific properties listed below. All events also include `source: "circuly_subscriptions"`. Test events additionally include `test: true`.

### Subscription lifecycle

| Metric name                | Trigger                                   | Properties                      |
| -------------------------- | ----------------------------------------- | ------------------------------- |
| **Subscription Created**   | New subscription contract activated       | `originOrderId`, `source`       |
| **Subscription Renewed**   | Billing cycle completed successfully      | `orderId`                       |
| **Subscription Cancelled** | Contract cancelled (by customer or admin) | `previousStatus`                |
| **Subscription Paused**    | Subscription paused by customer or admin  | `customerId`                    |
| **Subscription Resumed**   | Paused subscription resumed               | `customerId`, `nextBillingDate` |

### Payments

| Metric name                        | Trigger                                   | Properties                    |
| ---------------------------------- | ----------------------------------------- | ----------------------------- |
| **Subscription Payment Succeeded** | Shopify billing attempt succeeds          | `orderId`                     |
| **Subscription Payment Failed**    | Shopify billing attempt fails             | `errorCode`                   |
| **Payment Retry Scheduled**        | Failed payment queued for automatic retry | `nextRetryAt`, `attemptCount` |

### Billing

| Metric name                       | Trigger                                       | Properties                           |
| --------------------------------- | --------------------------------------------- | ------------------------------------ |
| **Subscription Cycle Skipped**    | Customer skips a billing cycle                | `cycleIndex`                         |
| **Subscription Buyout Initiated** | Customer starts buying out their subscription | `customerId`, `buyoutPrice`          |
| **Subscription Buyout Completed** | Buyout order completed                        | `draftOrderId`, `orderId`, `assetId` |

### Invoices

| Metric name         | Trigger                                         | Properties                                     |
| ------------------- | ----------------------------------------------- | ---------------------------------------------- |
| **Invoice Created** | Draft or final invoice generated                | `invoiceNumber`, `totalAmount`, `currencyCode` |
| **Invoice Paid**    | Invoice marked as paid after successful billing | `invoiceNumber`, `totalAmount`, `currencyCode` |
| **Invoice Overdue** | Invoice not paid by due date (billing failure)  | `invoiceNumber`, `totalAmount`, `attemptCount` |

## Payload structure

All events are sent in the Klaviyo Events API v3 format:

```json theme={null}
{
  "data": {
    "type": "event",
    "attributes": {
      "metric": {
        "data": {
          "type": "metric",
          "attributes": { "name": "Subscription Created" }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "email": "customer@example.com",
            "first_name": "Jane",
            "last_name": "Doe"
          }
        }
      },
      "properties": {
        "originOrderId": "gid://shopify/Order/123",
        "source": "circuly_subscriptions"
      },
      "time": "2026-02-12T15:30:00.000Z"
    }
  }
}
```

## Advanced flow patterns

The starter flows installed by Circuly are single-step. Use the prompts below with [Klaviyo's MCP server](https://developers.klaviyo.com/en/docs/klaviyo_mcp_server) to build richer multi-step flows.

### Payment recovery sequence

```text theme={null}
Create a flow triggered by the "Subscription Payment Failed" metric.
Step 1: Send an email immediately with subject "Action needed: payment issue with your subscription".
Step 2: Wait 2 days.
Step 3: Add a conditional split — check if the profile has received a
"Subscription Payment Succeeded" event in the last 2 days.
  - If yes: exit the flow.
  - If no: send a reminder email with subject "Your subscription payment is still pending".
Step 4: Wait 5 more days, send a final urgent reminder with subject
"Last chance: update your payment to keep your subscription".
Add a trigger filter: only enter this flow if event property "source" = "circuly_subscriptions".
```

### Cancellation win-back drip

```text theme={null}
Create a flow triggered by the "Subscription Cancelled" metric.
Step 1: Wait 1 day, send "We're sorry to see you go" with a feedback survey link.
Step 2: Wait 7 days. Add a conditional split — check if the profile has received
"Subscription Created" in the last 7 days.
  - If yes: exit (they re-subscribed).
  - If no: send "We miss you" email with a re-subscribe CTA.
Step 3: Wait 14 more days, send a final win-back offer with a discount code.
```

### Pause re-engagement

```text theme={null}
Create a flow triggered by the "Subscription Paused" metric.
Step 1: Send a confirmation email "Your subscription is paused".
Step 2: Wait 14 days. Add a conditional split — check if the profile has received
"Subscription Resumed" in the last 14 days.
  - If yes: exit.
  - If no: send "Ready to resume?" with a resume CTA.
Step 3: Wait 30 more days, send a final check-in with subject
"Your subscription is still on hold".
```

### Welcome series

```text theme={null}
Create a flow triggered by the "Subscription Created" metric.
Step 1: Send a welcome email with subject "Welcome to your subscription!".
Include the event property "originOrderId" as a link to the order.
Step 2: Wait 3 days, send a follow-up with subject "Getting the most out of your subscription"
with product tips and FAQs.
Step 3: Wait 7 days, send "How's it going?" with a feedback request.
Add a trigger filter: event property "source" = "circuly_subscriptions".
```

### Invoice escalation

```text theme={null}
Create a flow triggered by the "Invoice Overdue" metric.
Step 1: Send immediately with subject "Your invoice {{ event.invoiceNumber }} is overdue".
Include the event properties "invoiceNumber" and "totalAmount" in the email body.
Step 2: Wait 3 days, send a second reminder with subject "Reminder: outstanding invoice".
Step 3: Wait 7 more days, send a final notice with subject "Final notice: invoice overdue".
Add a trigger filter: only enter if event property "attemptCount" >= 2.
```

### Buyout upsell after loyalty

```text theme={null}
Create a flow triggered by the "Subscription Renewed" metric.
Add a trigger filter: the profile must have received "Subscription Renewed"
at least 6 times (long-term subscriber).
Step 1: Send an email with subject "You've been with us for a while — want to own it?"
with a buyout CTA explaining the option to purchase the product outright.
```

### Retry awareness

```text theme={null}
Create a flow triggered by the "Payment Retry Scheduled" metric.
Step 1: Send an email with subject "We'll retry your payment on {{ event.nextRetryAt }}".
Include event properties "nextRetryAt" and "attemptCount" in the body.
Add a trigger filter: only enter if "attemptCount" >= 2 (skip first retry).
```

## Segments

Use these prompts to create customer segments for targeted campaigns.

### At-risk subscribers

```text theme={null}
Create a segment of profiles who have received "Subscription Payment Failed"
at least once in the last 30 days AND have NOT received "Subscription Payment Succeeded"
in the last 30 days. Name it "At-Risk: Payment Issues".
```

### Paused subscribers

```text theme={null}
Create a segment of profiles who have received "Subscription Paused"
in the last 60 days AND have NOT received "Subscription Resumed"
in the last 60 days. Name it "Paused Subscribers".
```

### Churned subscribers

```text theme={null}
Create a segment of profiles who have received "Subscription Cancelled"
in the last 90 days AND have NOT received "Subscription Created"
in the last 90 days. Name it "Churned Subscribers".
```

### Loyal subscribers

```text theme={null}
Create a segment of profiles who have received "Subscription Renewed"
at least 3 times in the last 180 days. Name it "Loyal Subscribers".
```

### Overdue invoices

```text theme={null}
Create a segment of profiles who have received "Invoice Overdue"
in the last 14 days. Name it "Overdue Invoices".
```

### Buyout candidates

```text theme={null}
Create a segment of profiles who have received "Subscription Renewed"
at least 6 times in the last 365 days AND have NOT received
"Subscription Buyout Initiated" in the last 365 days. Name it "Buyout Candidates".
```

## Troubleshooting

| Issue                                   | Solution                                                                              |
| --------------------------------------- | ------------------------------------------------------------------------------------- |
| Events not appearing in Klaviyo         | Check that your API key starts with `pk_` and use **Test Connection** in Circuly      |
| Flow not triggering                     | Verify the metric name matches exactly — Klaviyo metric names are case-sensitive      |
| Wrong customer receiving emails         | Circuly resolves the customer email from the subscription contract record             |
| Rate limit errors                       | Klaviyo returns HTTP 429; Circuly logs these as `RATE_LIMITED` in the integration log |
| Test events triggering production flows | Add a trigger filter excluding events where the `test` property equals `true`         |

<Card title="Need help?" icon="envelope" href="mailto:miguel@circuly.io">
  Email us at [miguel@circuly.io](mailto:miguel@circuly.io) with your store URL and a description of what's happening.
</Card>