Get a weekly Paddle MRR report, split into new, expansion and churn

SKILL.md---
name: paddle-weekly-mrr-report
description: "Every Monday: MRR from Paddle Billing, the change since last week, and the new, expansion, contraction and churned MRR that explain it. Use when the user asks for this, or when it runs on a schedule."
---

# Paddle weekly MRR report

Every Monday: MRR from Paddle Billing, the change since last week, and the new, expansion, contraction and churned MRR that explain it.

For SaaS founders who bill through Paddle and want the Monday number without logging in. Paddle's metrics API returns MRR as a daily series (as of October 2026), but the API gives one net figure, not the story behind it: which new customers arrived, who upgraded, and who left.

The agent takes the headline MRR from Paddle itself, then snapshots every active subscription each week and compares it with last week's snapshot to split the change. You see that a $1,840 rise was $2,310 of new business held back by $980 of churn, and which accounts made up the churn.

## Two ways to get the data

Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used.

## Route A: API or MCP server

### What you need

- A Paddle API key with `metrics.read` and `subscription.read` (Paddle > Developer tools > Authentication). Keys created before the metrics API need `metrics.read` added.
- The Paddle MCP server (`https://mcp.paddle.com/mcp`) with that key as a bearer token, or the key in `PADDLE_API_KEY` for direct calls to `https://api.paddle.com`.

If something is missing, say what and stop; do not invent numbers.

### Steps

1. **Read MRR from Paddle** (Paddle): Call `GET /metrics/monthly-recurring-revenue` with `from` 8 weeks ago and `to` today (dates; `to` is exclusive). Each point in `timeseries` is one day in your primary balance currency, with `amount` in the lowest denomination; take every seventh point for the weekly history. It needs the `metrics.read` permission.
2. **Snapshot every subscription** (Paddle): Page through `GET /subscriptions?status=active,past_due&per_page=200`, following `meta.pagination.next`. For each, add `items[].price.unit_price.amount` times `quantity`, normalize it to a month with `billing_cycle.interval` and `frequency` (a yearly price divides by 12), and take off a `recurring` discount. Save `{ subscription_id: monthly_value }` to a JSON file.
3. **Split the change**: Compare with last Monday's snapshot. New: subscriptions that were not there. Churned: subscriptions that disappeared or are now `canceled` or `paused`. Expansion and contraction: the same subscription at a higher or lower monthly value. Any gap between this sum and Paddle's own MRR change goes on an "Other" line (exchange rates and timing).
4. **Post the tile**: MRR is the headline with 8 weeks of history; new, expansion, contraction and churn go in the glance, and the biggest movers by customer in the opened card. On the first run there is no earlier snapshot, so report only the total and the subscriptions whose `started_at` falls in the last 7 days.

## Route B: the browser

### What you need

- Signed in to Paddle Billing (vendors.paddle.com) with a role that can view subscriptions, customers and the home dashboard; 2FA done by the person first.

If something is missing, say what and stop; do not invent numbers.

### Steps

Start at https://vendors.paddle.com/subscriptions. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears.

1. **Read the headline MRR**: From the Paddle Billing dashboard open the home overview (the Paddle logo in the sidebar). The Billing charts there show MRR for the selected period; set the period to cover the last 8 weeks and note today's value and the value from one week ago. If your account still uses ProfitWell Metrics for MRR, read it from that dashboard instead and say so on the card.
2. **Export active and past-due subscriptions**: Go to **Subscriptions**, filter **Status** to `Active` and `Past due`, and use **Export** to download the CSV, since the list pages 25 at a time. Keep the subscription ID, customer, product and price, billing cycle, quantity and next payment amount.
3. **Work out each monthly value**: For each row, turn the recurring charge into a month: a yearly price divides by 12, a quarterly one by 3, after any recurring discount shown on the subscription. Save the list with today's date.
4. **Split the week's change**: Compare with last Monday's saved list. Subscriptions that are new this week are new MRR, ones that are gone or now show **Canceled** or **Paused** are churn, and the same subscription at a higher or lower monthly value is expansion or contraction. Any gap against the MRR chart goes on an "Other" line. For the movers, open the customer from the subscription to get the name.

Note: The subscriptions list is the dependable part of this route: it exports in full. The MRR figure depends on which charts your Paddle account shows on the home page, and accounts that still use ProfitWell Metrics read it there. On the first run there is no earlier list, so report only the total and the subscriptions started in the last 7 days.

## The report

- **MRR** today and the change since last Monday, with an 8-week trend.
- **The split**: new, expansion, contraction and churned MRR, with subscription counts.
- **Biggest movers**: the customers behind the largest new, upgraded and churned amounts.
- One line on what changed the week, for example "Churn doubled: 4 of 9 cancellations were past due for 30 days first".

## Post it to Briefkin

When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on.

```bash
[ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env
curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d @- <<'JSON'
{
  "v": 1,
  "event_id": "paddle-weekly-mrr-report/<date of this run, e.g. 2026-10-16>",
  "item_key": "paddle-weekly-mrr-report",
  "project": "Acme",
  "source": "Paddle weekly MRR report skill",
  "kind": "metric",
  "title": "MRR up $1,840 this week",
  "metric": {
    "label": "MRR",
    "value": 48620,
    "prefix": "$",
    "better": "higher",
    "period_start": "<start of the period, ISO 8601>",
    "period_end": "<end of the period, ISO 8601>"
  },
  "glance": [
    {
      "type": "Grid",
      "props": {
        "columns": 4
      },
      "children": [
        {
          "type": "Stat",
          "props": {
            "label": "New",
            "value": "+$2,310",
            "tone": "ok"
          }
        },
        {
          "type": "Stat",
          "props": {
            "label": "Expansion",
            "value": "+$640",
            "tone": "ok"
          }
        },
        {
          "type": "Stat",
          "props": {
            "label": "Contraction",
            "value": "-$130"
          }
        },
        {
          "type": "Stat",
          "props": {
            "label": "Churned",
            "value": "-$980",
            "tone": "bad"
          }
        }
      ]
    }
  ],
  "widget": [
    {
      "type": "Table",
      "props": {
        "columns": [
          "Movement",
          "Subscriptions",
          "MRR"
        ],
        "align": [
          "left",
          "right",
          "right"
        ],
        "rows": [
          [
            "New",
            23,
            "+$2,310"
          ],
          [
            "Expansion",
            7,
            "+$640"
          ],
          [
            "Contraction",
            2,
            "-$130"
          ],
          [
            "Churned",
            9,
            "-$980"
          ],
          [
            "Net change",
            "",
            "+$1,840"
          ]
        ]
      }
    },
    {
      "type": "Table",
      "props": {
        "columns": [
          "Customer",
          "Change",
          "MRR"
        ],
        "align": [
          "left",
          "left",
          "right"
        ],
        "rows": [
          [
            "Northwind Labs",
            "New, Team yearly",
            "+$290"
          ],
          [
            "Contoso",
            "Pro to Team",
            "+$180"
          ],
          [
            "Tailspin Studio",
            "Canceled, past due 34 days",
            "-$240"
          ],
          [
            "Wingtip Media",
            "Canceled",
            "-$160"
          ]
        ]
      }
    },
    {
      "type": "Callout",
      "props": {
        "text": "Churn was 9 subscriptions and $980; 4 of them had been past due for over 30 days before they canceled.",
        "tone": "warn"
      }
    }
  ],
  "size": "md"
}
JSON
```

Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report.

Set `period_start` and `period_end` to the window the number covers: the tile names it from them ("Last 7 days", "Today", "This month"). For a count right now (open items, a balance), send `"period_label": ""` so no period shows; for another name, send it as `period_label` (at most 24 characters).

## Run it on a schedule

Suggested: Mondays at 8:00 (`0 8 * * 1`). From cron, with the agent signed in on that machine:

```bash
0 8 * * 1 claude -p "Run the paddle-weekly-mrr-report skill"
# Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run
```

Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/paddle-weekly-mrr-report#schedule

Source: https://briefkin.dev/skills/paddle-weekly-mrr-report