Skip to main content

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.

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.
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.

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 nameTriggerProperties
Subscription CreatedNew subscription contract activatedoriginOrderId, source
Subscription RenewedBilling cycle completed successfullyorderId
Subscription CancelledContract cancelled (by customer or admin)previousStatus
Subscription PausedSubscription paused by customer or admincustomerId
Subscription ResumedPaused subscription resumedcustomerId, nextBillingDate

Payments

Metric nameTriggerProperties
Subscription Payment SucceededShopify billing attempt succeedsorderId
Subscription Payment FailedShopify billing attempt failserrorCode
Payment Retry ScheduledFailed payment queued for automatic retrynextRetryAt, attemptCount

Billing

Metric nameTriggerProperties
Subscription Cycle SkippedCustomer skips a billing cyclecycleIndex
Subscription Buyout InitiatedCustomer starts buying out their subscriptioncustomerId, buyoutPrice
Subscription Buyout CompletedBuyout order completeddraftOrderId, orderId, assetId

Invoices

Metric nameTriggerProperties
Invoice CreatedDraft or final invoice generatedinvoiceNumber, totalAmount, currencyCode
Invoice PaidInvoice marked as paid after successful billinginvoiceNumber, totalAmount, currencyCode
Invoice OverdueInvoice not paid by due date (billing failure)invoiceNumber, totalAmount, attemptCount

Payload structure

All events are sent in the Klaviyo Events API v3 format:
{
  "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 to build richer multi-step flows.

Payment recovery sequence

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

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

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

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

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

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

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

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

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

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

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

Create a segment of profiles who have received "Invoice Overdue"
in the last 14 days. Name it "Overdue Invoices".

Buyout candidates

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

IssueSolution
Events not appearing in KlaviyoCheck that your API key starts with pk_ and use Test Connection in Circuly
Flow not triggeringVerify the metric name matches exactly — Klaviyo metric names are case-sensitive
Wrong customer receiving emailsCirculy resolves the customer email from the subscription contract record
Rate limit errorsKlaviyo returns HTTP 429; Circuly logs these as RATE_LIMITED in the integration log
Test events triggering production flowsAdd a trigger filter excluding events where the test property equals true

Need help?

Email us at miguel@circuly.io with your store URL and a description of what’s happening.