> ## Documentation Index
> Fetch the complete documentation index at: https://help.ciclostrategy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Stripe
> Track revenue, subscriptions, and customer metrics from Stripe — monthly and annual recurring revenue, churn, balance, and more — as live KPIs in Ciclo.
## Overview
Connecting [Stripe](https://stripe.com) brings your payments and subscription data into your
strategy. Ciclo reads your charges, subscriptions, customers, invoices, and balance so the
numbers that matter — revenue, monthly and annual recurring revenue, new and churned
subscriptions, customer growth — appear as key performance indicators
([KPIs](/features/performance-kpis)) alongside the rest of your strategy and refresh
automatically.
You connect Stripe with a **read-only Restricted API Key** you create in Stripe (see
[Connect Stripe](#connect-stripe) below). The sync is one-way (Stripe → Ciclo): Ciclo reads your
account to populate KPIs and — because the key is read-only — can never create charges, change
subscriptions, or alter anything in Stripe.
Connecting and configuring integrations is limited to **organisation administrators**.
Stripe does not link to [Actions](/features/actions) — it powers revenue and customer KPIs only.
## Before you start
* You need an **administrator** role in Ciclo — the **Connect** and **Configure** buttons are
hidden for everyone else.
* You need access to your **Stripe Dashboard** with permission to create API keys.
## Connect Stripe
Stripe connects with a **read-only Restricted API Key** — there's no pop-up login. You create a
key in Stripe that can *read* the data Ciclo needs (and nothing else), then paste it into Ciclo
once. Setting the key's permissions is the only fiddly part, so it's worth following closely.
Go to **Settings** from the account menu, open the **Connected Apps** tab, find **Stripe**,
and select **Connect**. A **Connect Stripe** dialog opens, listing the required permissions
and a link to create the key.
In the dialog, select **Create a restricted API key →**. This opens Stripe's **Create
restricted key** page in a new tab. Give the key a name you'll recognise later — for example
*Ciclo Strategy*.
Stripe groups its permissions, and you only ever need to grant **Read**. Two permission
groups cover everything Ciclo reads:
* Set **Core** to **Read**
* Set **Billing** to **Read**
* Leave every other group as **None**
That's all you need. **Core** covers balance, charges, refunds, and customers; **Billing**
covers invoices and subscriptions — exactly the data Ciclo's KPIs use.
Select **Create key** at the bottom of Stripe's page, then **copy** the key — it begins with
`rk_`. Stripe shows the full key only once, so copy it before leaving the page.
Back in the **Connect Stripe** dialog, paste the key into the **API key** field and select
**Connect**. Ciclo checks the key can read charges, customers, subscriptions, invoices, and
balance, then stores it encrypted — the key is never shown again.
On success, Stripe shows a green **Connected** status, named after your Stripe business.
If Ciclo reports the key is **missing read access** to one of the resources, the restricted key
was created without that permission. Edit the key in Stripe (or create a new one), make sure
**Core** and **Billing** are both set to **Read**, then reconnect.
Treat the restricted key like a password. Because it's **read-only** it can never move money or
change your Stripe data — but if it's ever exposed, **roll** (delete) it in Stripe and reconnect
with a fresh key. Your KPIs reconnect automatically.
## Track Stripe KPIs
On the **Stripe** row, select **Configure**, then **Add New KPI**.
Give the KPI a clear name, then choose a **Query Template** — see the
[catalogue below](#available-stripe-kpis).
Select **Create KPI**. It appears on your [Performance page](/features/performance-kpis)
and refreshes automatically.
### Available Stripe KPIs
* **Revenue (30 days)** — total value of successful charges in the last 30 days.
* **Available Balance** — current balance available for payout.
* **Refunds (30 days)** — total value of refunds issued in the last 30 days.
* **Monthly Recurring Revenue (MRR)** — computed from all active subscriptions, normalised
to a monthly amount.
* **Annual Recurring Revenue (ARR)** — MRR × 12.
* **Active Subscriptions** — count of all currently active subscriptions.
* **New Subscriptions (30 days)** — subscriptions created in the last 30 days.
* **Canceled Subscriptions (30 days)** — subscriptions canceled in the last 30 days.
* **Total Customers** — total customers in your Stripe account.
* **New Customers (30 days)** — customers created in the last 30 days.
* **Outstanding Invoices (value)** — total value of all open (unpaid) invoices.
* **Outstanding Invoices (count)** — number of open (unpaid) invoices.
## Customising a KPI (optional)
You don't need any of this to get great results — the built-in templates are designed to be
accurate on their own. Pick a template and you're done. Expand the sections below only if you
want to fine-tune or go further.
Date-windowed KPIs use a rolling window (e.g. the last 30 days). If a template is close but
not quite right, you can adjust it instead of starting from scratch — for example, change the
reporting period from the last 30 days to the last 90 days by editing `{date-30d}` to
`{date-90d}`. The templates simply fill the **Query** field in for you; editing it is optional.
Power users can point a KPI at other Stripe data. For everything that's possible, see:
The resources, list endpoints, and filters Stripe makes available.
For very large accounts, count- and sum-based KPIs (customers, charges, refunds, invoices) are
read up to a generous limit and flagged as **approximate** beyond it. Likewise, **Available
Balance** is summed across currencies when you hold more than one, and shown as approximate.
The values still track the right trend — they just stop being exact at the extremes.
## Disconnecting Stripe
Select **Disconnect** on the Stripe row. Ciclo shows which KPIs rely on Stripe before you
confirm, then deletes its stored copy of the key so it can no longer read your account.
To fully revoke access, also **delete (roll) the restricted key** in your Stripe Dashboard
(**Developers → API keys**) — disconnecting removes Ciclo's copy, but the key itself keeps
working in Stripe until you delete it there.
Disconnecting **preserves history** — KPIs keep their recorded values. They stop syncing until
you reconnect, then resume automatically.
## Related