---
title: "Get top payment customers"
method: GET
path: "/api/apps/{app_id}/payments/analytics/top-customers"
---

# Get top payment customers

`GET /api/apps/{app_id}/payments/analytics/top-customers`

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Returns customers ranked by live payment amount or count, highest first.

Customer details are enriched through Stripe. Amounts across currencies are summed without conversion, so filter to one currency with `currencies` before comparing them.

Send `start_date` and `end_date` together to set a window. With neither, or only one of the two, `period` selects the last 7, 30, or 90 whole UTC days including today.

Returns a single batch of up to `limit` records, with no cursor to retrieve the rest.

Results come from an analytics store and can lag behind the payment provider.

Requires read access to the app.

## Path parameters

- `app_id` string, required — ID of the Base44 app.

## Query parameters

- `start_date` string, date-time, nullable — Start of the window as an ISO 8601 timestamp. Send with end_date. Defaults to the period window.
- `end_date` string, date-time, nullable — End of the window as an ISO 8601 timestamp. Send with start_date. Defaults to now when using period.
- `period` '7d' | '30d' | '90d' — Fallback window. Either `7d`, `30d`, or `90d`. Defaults to `30d`. Used unless both dates are supplied.
- `order_by` 'amount' | 'transactions' — Ranking metric. Either `amount` or `transactions`. Defaults to `amount`. Highest values come first.
- `limit` integer — Maximum customers to return, from 1 through 10. Defaults to 5.
- `currencies` string, nullable — Comma-separated currency codes, for example `usd,eur`. Defaults to no currency filter. Use one currency when comparing amounts.

## Response `200`

Successful Response

- TopCustomersResponse — Response with top customers list.
  - `customers` TopCustomer[], required — Customers ranked by the requested metric, highest first. Empty when no matching payments are found.
    - `customer_id` string, required — Payment provider customer ID.
    - `name` string, nullable — Customer name from Stripe, or `null` when enrichment is unavailable. Defaults to `null`.
    - `email` string, nullable — Customer email from Stripe, or `null` when enrichment is unavailable. Defaults to `null`.
    - `transaction_count` integer — Number of payments in the selected window. Defaults to 0.
    - `total_amount` integer — Total payment amount in the currencies' smallest units. Filter to one currency before interpreting this value. Defaults to 0.

## Other responses

- `401` — Missing or invalid credentials.
- `403` — You don't have access to this app, or the app does not exist. A missing app and an app you cannot reach are deliberately the same answer.
- `404` — The app is outside the credential grant.
- `409` — The workspace requires an unlocked SSO session.
- `422` — Validation Error

## Changes

- **2026-09-15** `ca10c5ce328c` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/base44/apis/base44-app-management-api/changes/api/apps/:app_id/payments/analytics/top-customers/get.md)

---

[API](https://skmtc.dev/base44/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/base44/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/base44/apis/base44-app-management-api/revisions/5e69adeb8667?raw)