---
name: fetch-seller-metrics
description: Build a seller dashboard from the partner API with the seller `api_key` — revenue and MRR metrics as timeseries, transactions (`include=customer`), adjustments and refunds, and the products your integration created (filtered by `external_id`).
metadata:
  internal: true
---

# Fetch seller metrics and build a dashboard

## When to use this skill

Use this skill once a seller is live, to surface their business in your platform: revenue metrics, transactions, adjustments (refunds/credits), and the product catalog your integration created. Make this data available to your platform agent too, so the seller can ask natural-language questions like "how much did I make last month?"

All calls use the seller's **`api_key`** (see [`partner-api-basics`](/partners/embed-billing/get-started/api-basics)) and work in both sandbox and live.

## Revenue and other metrics

Call `GET /metrics/revenue` with a `from`/`to` date range for net revenue over time. `amount` is a **string in the smallest unit** of `currency_code` (cents for USD), converted to the seller's primary balance currency.

```bash
curl "https://api.paddle.com/metrics/revenue?from=2025-09-01&to=2025-09-05" \
  -H "Authorization: Bearer $SELLER_API_KEY"
```

```json
{
  "data": {
    "timeseries": [
      { "timestamp": "2025-09-01T00:00:00Z", "amount": "284500", "count": 12 },
      { "timestamp": "2025-09-02T00:00:00Z", "amount": "312750", "count": 14 }
    ],
    "currency_code": "USD",
    "interval": "day",
    "starts_at": "2025-09-01T00:00:00Z",
    "ends_at": "2025-09-05T00:00:00Z"
  }
}
```

The API also exposes `/metrics/mrr`, `/metrics/mrr-change`, and `/metrics/active-subscribers`. They return timeseries in the same shape and take the same `from`/`to` params. Present revenue as a figure plus a chart over the last 7 days, month, and 3 months. Some metrics aren't available in sandbox — check the API docs before implementing.

## List transactions

`GET /transactions` returns the last 30 transactions. By default a transaction includes `customer_id` but not the email — add `include=customer` to embed the customer entity so you can show who each belongs to.

```bash
curl "https://api.paddle.com/transactions?include=customer" \
  -H "Authorization: Bearer $SELLER_API_KEY"
```

Show `details.totals.grand_total` (amount), `items[]` (what they bought), `created_at`/`completed_at`, and `status`. Map status:

| Status              | Label     | Meaning                                                                                  |
| ------------------- | --------- | ---------------------------------------------------------------------------------------- |
| `draft`, `ready`    | Draft     | Created but incomplete or abandoned                                                      |
| `billed`            | Billed    | Has an invoice number; a legal record (uncommon in partner integrations)                 |
| `paid`, `completed` | Completed | Fully paid — a successful sale                                                           |
| `canceled`          | Canceled  | Canceled; if an invoice, no longer due                                                   |
| `past_due`          | Past due  | Payment overdue; subscription is in [dunning](/concepts/retain/payment-recovery-dunning) |

## List adjustments

`GET /adjustments` returns refunds, credits, and chargebacks. Show `totals.total`, `action`, `reason`, `status`, and `created_at`.

```bash
curl https://api.paddle.com/adjustments \
  -H "Authorization: Bearer $SELLER_API_KEY"
```

`action` is `refund`, `credit`, `chargeback` / `chargeback_warning` (show as "Chargeback"), `chargeback_reverse` / `chargeback_warning_reverse` (show as "Chargeback reversal"), or `credit_reverse`. `status` is `pending_approval` (most live refunds start here), `approved`, `rejected`, or `reversed`.

## List products

Sellers may create products in the dashboard that aren't linked to your integration. Show only yours by filtering on the `external_id` you set in `import_meta` when [creating products](/partners/embed-billing/build-seller-integrations/create-catalog). Add `include=prices` to show pricing, and `status[]` (`active` / `archived`) to hide archived ones.

```bash
curl "https://api.paddle.com/products?external_id=your-internal-id&include=prices&status[]=active" \
  -H "Authorization: Bearer $SELLER_API_KEY"
```

## Common pitfalls

- **Parsing `amount` / `grand_total` as a number.** They're strings in the smallest currency unit — keep them as strings and format for display.
- **Expecting all metrics in sandbox.** Some aren't available there; check before relying on them.
- **Omitting `include=customer`.** You'll only have `customer_id`, not the email, and need extra calls.
- **Listing all products.** Filter by your `external_id` so you show only your integration's catalog, not products the seller made in the dashboard.

## Verify

- `GET /metrics/revenue?from=…&to=…` returns `200` with a `timeseries` array.
- `GET /transactions?include=customer` returns recent transactions with embedded customers.
- `GET /products?external_id=…&include=prices` returns only your integration's products, each with prices.

## Related docs

- [Build a seller dashboard](/partners/embed-billing/manage-sellers/metrics-dashboards)
- [Metrics](/api-reference/metrics), [Transactions](/api-reference/transactions), [Adjustments](/api-reference/adjustments), [Products](/api-reference/products)