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

# Reporting

> Build a partner leaderboard or revenue chart in your app from the /v2/reports endpoints.

The report endpoints return totals that are already aggregated. One call per widget.

app.acme.com/partners/leaderboard

Revenue, 30 days**\$48,210**Commissions**\$7,232**

1\. Sam Rivera\$12,840 · 41 customers
2\. Priya Shah\$9,310 · 28 customers
3\. Leo Martins\$6,125 · 19 customers

Stats from /reports/overview, sparkline from /reports/timeseries, rows from /reports/partners.

## Pick an endpoint

| Endpoint | Returns | Use it for |
| - | - | - |
| `GET /v2/reports/overview` | Totals, revenue and commissions per currency | KPI tiles |
| `GET /v2/reports/timeseries` | One point per `day`, `week` or `month` | Revenue charts |
| `GET /v2/reports/partners` | One row per partner, ranked | Leaderboards |
| `GET /v2/reports/links` | One row per referral link, ranked | Top links |
| `GET /v2/reports/customers` | Counts by status (`trialing`, `active`, `canceled`, `suspended`) | Customer health |

All take `program_id`, `start_date` and `end_date` (`YYYY-MM-DD`, both days included). Leave the dates out for all time.

## Build a leaderboard

Rank partners by revenue for the last 30 days. Amounts are strings in cents.

```ts TypeScript theme={"system"}
import { ToltApiClient } from "@tolt/api";

const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });

const { data: rows } = await tolt.reports.partners({
  start_date: "2026-09-20",
  end_date: "2026-10-19",
  currency: "USD",
  sort: "revenue",
  limit: 10,
});

const leaderboard = rows.map((r, i) => ({
  rank: i + 1,
  name: [r.first_name, r.last_name].filter(Boolean).join(" ") || r.email,
  revenue: Number(r.revenue) / 100,
  customers: r.customers,
}));
```

```python Python theme={"system"}
import os
from datetime import date
from tolt import ToltApi

client = ToltApi(token=os.environ["TOLT_API_KEY"])

rows = client.reports.partners(
    start_date=date(2026, 9, 20),
    end_date=date(2026, 10, 19),
    currency="USD",
    sort="revenue",
    limit=10,
).items

for rank, r in enumerate(rows, start=1):
    print(
        rank, r.first_name, r.last_name, int(r.revenue) / 100, r.customers
    )
```

```bash cURL theme={"system"}
curl -G https://platform.tolt.com/v2/reports/partners \
  -d start_date=2026-09-20 \
  -d end_date=2026-10-19 \
  -d currency=USD \
  -d sort=revenue \
  -d limit=10 \
  -H "Authorization: Bearer $TOLT_API_KEY"
```

Sort by `revenue`, `commissions`, `clicks` or `customers` (default `revenue`, descending). Page with `limit` (default 10, up to 100) and `offset`, while `has_more` is `true`.

## Chart revenue over time

```ts theme={"system"}
const { data: points } = await tolt.reports.timeseries({
  start_date: "2026-01-01",
  end_date: "2026-06-30",
  granularity: "month",
  currency: "USD",
});
// [
//   {
//     period: "2026-01-01",
//     revenue: "482100",
//     commissions: "72315",
//     customers: 34,
//     clicks: 1290,
//   },
//   ...
// ]
```

`period` is the first day of each bucket; weeks start on Monday. Buckets with no activity are left out, so fill gaps with zeros before you plot.

## Metric definitions

| Metric | Means |
| - | - |
| `revenue` | Sum of transactions that are not refunded |
| `commissions` | Sum of approved and paid commissions |
| `customers` | Customers who converted (not leads), counted on the day they became active |
| `clicks` | Visits through a partner's links |
| `conversion_rate` | `customers / clicks`, as a percentage rounded to 2 decimals (`4.2` = 4.2%), `0` when there are no clicks |

`/reports/overview` differs on one point: its `customer_count` includes leads and counts customers by the day they were created. `/reports/customers` has no lead count and filters by the day customers became active.

In `/reports/links`, revenue reaches a link through the transaction's click, while commissions and customers go through the customer's link. Revenue recorded without a click doesn't show under any link.

> [!WARNING]
>
> `/partners`, `/links` and `/timeseries` add up amounts across currencies. If your programs sell in more than one currency, pass `currency` (for example `USD`, any case) or scope with `program_id`. `currency` filters transactions and commissions only, not clicks or customers, and records without a currency count as the program's currency (or USD). `/overview` already splits revenue and commissions into one entry per currency, and neither it nor `/customers` takes `currency`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.