# How to connect Polar to AI agents?

Connect Polar to Sequel with a read-only Organization Access Token and ask about MRR, churn, subscriptions, and usage billing in natural language.

Connect **Polar** to Sequel and ask about your revenue, subscriptions, customers, and usage-based billing in plain English — MRR, ARR, churn rate, LTV, failed payments, meter usage — from the Sequel app or any AI tool wired up to the [MCP server](/docs/install). Polar connects with a single access token, and Sequel only ever reads.

## What you'll need

- A **Polar organization** you can access the settings for.
- A **Polar Organization Access Token** (starts with `polar_oat_`) scoped to **read-only** permissions.

<Callout type="tip" title="Grant read scopes only">
The Polar connector ships only read tools — it cannot create, refund, or cancel anything. Granting your token only the `:read` scopes enforces that at Polar's end too, so the integration is safe even in principle. You can revoke or rotate the token in Polar at any time without touching your other integrations.
</Callout>

## Connect it

<Steps>
<Step title="Open a new connection">
In the Sequel dashboard, go to **Connections → New connection** and choose **Polar**.
</Step>

<Step title="Create an access token in Polar">
In Polar, go to **Organization Settings → Developers → New Token**. Give it a name, pick an expiry, and enable these read scopes:

`metrics:read`, `orders:read`, `subscriptions:read`, `customers:read`, `products:read`, `payments:read`, `refunds:read`, `disputes:read`, `discounts:read`, `checkouts:read`, `events:read`, `meters:read`, `customer_meters:read`, `organizations:read`

Leave every `:write` scope off.
</Step>

<Step title="Paste the token into Sequel">
Copy the token — Polar shows it only once — and paste it into the **API key** field on Sequel's Polar connector.
</Step>

<Step title="Choose the environment">
Leave **Server** blank (or set it to `production`) for your live organization. Enter `sandbox` if the token came from a Polar sandbox organization.
</Step>

<Step title="Test and save">
Sequel verifies the token against the Polar API and names the connection after your organization. A green check means it's live.
</Step>
</Steps>

<Callout type="info" title="Sandbox and production are separate accounts">
Polar's sandbox is a fully isolated deployment with its own organization and its own tokens — a sandbox token will not authenticate against production. If you want both, create two connections and set the environment on each.
</Callout>

## What you can query

Sequel exposes Polar as 14 read-only tools:

- **Metrics** — Polar's 55 pre-computed metrics as a time series with totals: MRR, ARR, committed MRR, churn rate, LTV, ARPU, revenue and net revenue, cashflow, average order value, gross margin, checkout conversion, per-reason cancellations, and seat metrics.
- **Orders** — individual purchases and renewals, filterable by status, date range, product, customer, discount, or subscription.
- **Subscriptions** — status, amount, trial windows, period boundaries, cancellation timestamps and reasons.
- **Customers** and **Customer state** — the customer list, plus a single call returning one customer's active subscriptions, granted benefits, and active meters.
- **Products** — your catalogue, with prices nested inside each product.
- **Payments**, **Refunds**, and **Disputes** — including failed payment attempts and their decline reasons.
- **Discounts** and **Checkouts** — code redemptions and checkout-funnel drop-off.
- **Meters**, **Meter quantities**, and **Events** — usage-based billing: what you meter, how much was consumed over time, and the raw ingested events behind it.

<Callout type="info" title="Amounts are in cents">
Polar returns every monetary value as an integer number of cents. Sequel leaves them that way so sums stay exact, and the metrics result includes a `units` row telling you which columns are currency, which are counts, and which are percentages.
</Callout>

## Try it

- "What's our MRR trend over the last six months?"
- "Which cancellation reason drove the most churn last quarter?"
- "How many payments failed last month, and for which customers?"
- "What's our checkout conversion rate by product?"

## Join it with other sources

Polar is most powerful next to your product data. With a database or product analytics tool also connected, ask:

> "For customers who churned in Polar last month, what features did they use in our Postgres `events` table?"

## Troubleshooting

| Symptom | Likely fix |
| --- | --- |
| Invalid or expired token | Re-check the token for typos, or mint a fresh Organization Access Token in Polar and paste it again. Tokens expire on the schedule you set when creating them. |
| A tool returns a permissions error | The token is missing the `:read` scope for that resource. Edit the token's scopes in Polar, or create a new one with the full read set above. |
| Authentication fails against the right-looking token | Check the environment. A `sandbox` token will not work against production, and vice versa. |
| A metrics question returns a validation error | The interval is too fine for the date range. Widen `interval` from `hour` to `day`, or from `day` to `month`, and ask again. |
| Data looks empty | Confirm there's data in the period you're asking about, and that the token belongs to the organization you expect — a token is bound to exactly one organization. |

## Limitations

Polar's public API has **no payouts or balance endpoints**, so questions about how much Polar has paid out, payout schedules, or your current balance can't be answered by any integration, Sequel included. Revenue questions work fine — just note that revenue is not the same as what reaches your bank account, since it's before Polar's fees, taxes remitted, and payout timing.

## Related

- [Connecting your first data source](/docs/connecting-your-first-data-source)
- [Chatting with your data](/docs/chatting-with-your-data)
- [Browse all integrations](/docs/integrations)