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

# Polar Integration

> Sync revenue data from Polar to power segments and automations

Connect your Polar account to automatically sync revenue metrics for all your subscribers. This enables powerful segmentation based on MRR and LTV.

## What is Polar?

[Polar](https://polar.sh) is a modern payment platform designed for developers, open source maintainers, and digital product creators. It offers subscriptions, one-time payments, and benefits management with a developer-friendly API.

## Connecting Polar

Unlike Stripe (which uses an app integration), Polar requires manual API key and webhook setup. Here's how to connect:

### Step 1: Get Your Polar API Key

1. Go to your [Polar Dashboard](https://polar.sh)
2. Navigate to **Settings** in your organization
3. Click **API & Webhooks**
4. Create a new **Organization Access Token**
5. Copy the token (format: `polar_oat_xxxxxxxxx`)

<Warning>
  Your API token is only shown once. Store it securely before closing the dialog.
</Warning>

### Step 2: Set Up Webhooks in Polar

1. In Polar, go to **Settings → Webhooks**
2. Click **Create Webhook Endpoint**
3. Enter your Sequenzy webhook URL:
   ```
   https://api.sequenzy.com/webhooks/polar/{your-company-id}
   ```
   <Note>
     You can find this URL in Sequenzy when connecting Polar—it's automatically shown in the connection modal.
   </Note>
4. Select these events to listen for:
   * `subscription.created`
   * `subscription.active`
   * `subscription.updated`
   * `subscription.canceled`
   * `subscription.revoked`
   * `order.created`
   * `order.paid`
   * `customer.created`
   * `customer.state_changed`
5. Click **Create** to save the webhook
6. Copy the **Webhook Secret** (format: `polar_whs_xxxxxxxxx`)

### Step 3: Connect in Sequenzy

1. Go to **Settings → Integrations** in Sequenzy
2. Click **Connect** next to Polar
3. Enter your:
   * **API Key** (from Step 1)
   * **Webhook Secret** (from Step 2)
4. Click **Connect Polar**

Sequenzy will immediately begin syncing your existing Polar customers.

## Synced Attributes

When connected, Sequenzy adds these attributes to each subscriber matched by email:

| Attribute | Type   | Description                                                                 |
| --------- | ------ | --------------------------------------------------------------------------- |
| `mrr`     | Number | Monthly Recurring Revenue in dollars (normalized from any billing interval) |
| `ltv`     | Number | Lifetime Value - total payments minus refunds                               |

### MRR Calculation

MRR is normalized from any billing interval:

* **Monthly**: Used as-is
* **Yearly**: Divided by 12
* **Weekly**: Multiplied by 52, then divided by 12
* **Daily**: Multiplied by 365, then divided by 12

Only `active` subscriptions count toward MRR.

### LTV Calculation

LTV sums all successful orders for a customer, minus any refunds. This gives you the true lifetime value accounting for partial refunds.

## Automatic Tags

Sequenzy automatically applies tags to subscribers based on their Polar subscription status:

| Tag            | Applied When                             |
| -------------- | ---------------------------------------- |
| `customer`     | Has an active subscription               |
| `cancelled`    | Subscription set to cancel at period end |
| `churned`      | Subscription has ended (revoked)         |
| `saas.monthly` | On a monthly billing interval            |
| `saas.yearly`  | On a yearly billing interval             |

These tags update automatically whenever subscription status changes via webhooks.

## Tracked Events

When you connect Polar, these events are automatically tracked for use in automations:

| Event                   | Triggered When                           |
| ----------------------- | ---------------------------------------- |
| `saas.purchase`         | New subscription or renewal              |
| `saas.purchase_monthly` | Monthly subscription purchase            |
| `saas.purchase_yearly`  | Yearly subscription purchase             |
| `saas.cancelled`        | Subscription set to cancel at period end |
| `saas.churn`            | Subscription revoked/ended               |
| `saas.upgrade`          | Subscription upgraded to higher plan     |
| `saas.downgrade`        | Subscription downgraded to lower plan    |
| `saas.refund`           | Order refunded                           |

## Using Revenue Data

### Building Segments

With MRR and LTV synced as numeric attributes, you can create sophisticated segments:

**Revenue-based segments:**

* `mrr >= 100` — High MRR customers
* `ltv > 1000` — Lifetime high-value customers
* `mrr >= 50 AND mrr < 200` — Mid-tier customers

**Combining with tags:**

* `tag = churned AND ltv > 500` — High-value churned customers (win-back targets)
* `tag = cancelled AND mrr >= 100` — At-risk high-value customers needing attention
* `tag = saas.yearly AND mrr >= 100` — Yearly enterprise customers

### Automations

Trigger automations when revenue attributes change:

* Send a thank-you email when `ltv` exceeds a threshold
* Trigger a win-back sequence when a subscriber gets the `churned` tag
* Notify your team when a high-value customer cancels

## Manual Sync

To re-sync revenue data at any time:

1. Go to **Settings → Integrations**
2. Find your connected Polar account
3. Click **Sync Revenue**

The sync processes all Polar customers and updates matching subscribers.

## How Matching Works

Subscribers are matched by email address (case-insensitive). A Polar customer with email `User@Example.com` will match a subscriber with email `user@example.com`.

If a Polar customer doesn't have an email or doesn't match any subscriber, they're skipped during sync.

## Troubleshooting

### Webhooks Not Arriving

1. Verify your webhook URL is correct in Polar settings
2. Check that you've selected the correct events
3. Ensure your Polar organization has the `webhooks:write` scope
4. Check Polar's webhook delivery logs for failed attempts

### Customers Not Syncing

1. Ensure the customer email in Polar matches a subscriber in Sequenzy
2. Try clicking **Sync Revenue** to force a re-sync
3. Check that your API key has the required scopes:
   * `customers:read`
   * `subscriptions:read`
   * `orders:read`

### Invalid Webhook Signature

If webhooks are failing with signature errors:

1. Verify you copied the complete webhook secret from Polar
2. Re-create the webhook in Polar and update the secret in Sequenzy
3. Ensure the secret starts with `polar_whs_`