> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get top payment customers
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
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.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json get /api/apps/{app_id}/payments/analytics/top-customers
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- PersonalAccessTokenAuth: []
paths:
/api/apps/{app_id}/payments/analytics/top-customers:
get:
summary: Get top payment customers
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
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.
operationId: get_top_customers_api_apps__app_id__payments_analytics_top_customers_get
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the Base44 app.
title: App Id
description: ID of the Base44 app.
example: 6820f3a4e7b91d003c45a1f2
- name: start_date
in: query
required: false
schema:
type: string
format: date-time
description: >-
Start of the window as an ISO 8601 timestamp. Send with end_date.
Defaults to the period window.
title: Start Date
description: >-
Start of the window as an ISO 8601 timestamp. Send with end_date.
Defaults to the period window.
example: '2026-08-01T00:00:00Z'
- name: end_date
in: query
required: false
schema:
type: string
format: date-time
description: >-
End of the window as an ISO 8601 timestamp. Send with start_date.
Defaults to now when using period.
title: End Date
description: >-
End of the window as an ISO 8601 timestamp. Send with start_date.
Defaults to now when using period.
example: '2026-08-31T23:59:59Z'
- name: period
in: query
required: false
schema:
enum:
- 7d
- 30d
- 90d
type: string
description: >-
Fallback window. Either `7d`, `30d`, or `90d`. Defaults to `30d`.
Used unless both dates are supplied.
default: 30d
title: Period
description: >-
Fallback window. Either `7d`, `30d`, or `90d`. Defaults to `30d`.
Used unless both dates are supplied.
example: 30d
- name: order_by
in: query
required: false
schema:
enum:
- amount
- transactions
type: string
description: >-
Ranking metric. Either `amount` or `transactions`. Defaults to
`amount`. Highest values come first.
default: amount
title: Order By
description: >-
Ranking metric. Either `amount` or `transactions`. Defaults to
`amount`. Highest values come first.
example: amount
- name: limit
in: query
required: false
schema:
type: integer
maximum: 10
minimum: 1
description: Maximum customers to return, from 1 through 10. Defaults to 5.
default: 5
title: Limit
description: Maximum customers to return, from 1 through 10. Defaults to 5.
example: 5
- name: currencies
in: query
required: false
schema:
type: string
description: >-
Comma-separated currency codes, for example `usd,eur`. Defaults to
no currency filter. Use one currency when comparing amounts.
title: Currencies
description: >-
Comma-separated currency codes, for example `usd,eur`. Defaults to
no currency filter. Use one currency when comparing amounts.
example: usd
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TopCustomersResponse'
'401':
description: Missing or invalid credentials.
'403':
description: >-
You don't have access to this app, the app does not exist, or its
workspace restricts payment management
(`app_payment_management_not_allowed`).
'404':
description: The app is outside the credential grant.
'409':
description: The workspace requires an unlocked SSO session.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- PersonalAccessTokenAuth:
- read_only
components:
schemas:
TopCustomersResponse:
properties:
customers:
items:
$ref: '#/components/schemas/TopCustomer'
type: array
title: Customers
description: >-
Customers ranked by the requested metric, highest first. Empty when
no matching payments are found.
example:
- customer_id: cus_T7mK2p9Q4r6S8v
email: jane@example.com
name: Jane Doe
total_amount: 10000
transaction_count: 4
type: object
required:
- customers
title: TopCustomersResponse
description: Response with top customers list.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
TopCustomer:
properties:
customer_id:
type: string
title: Customer Id
description: Payment provider customer ID.
example: cus_T7mK2p9Q4r6S8v
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: >-
Customer name from Stripe, or `null` when enrichment is unavailable.
Defaults to `null`.
example: Jane Doe
email:
anyOf:
- type: string
- type: 'null'
title: Email
description: >-
Customer email from Stripe, or `null` when enrichment is
unavailable. Defaults to `null`.
example: jane@example.com
transaction_count:
type: integer
title: Transaction Count
description: Number of payments in the selected window. Defaults to 0.
default: 0
example: 4
total_amount:
type: integer
title: Total Amount
description: >-
Total payment amount in the currencies' smallest units. Filter to
one currency before interpreting this value. Defaults to 0.
default: 0
example: 10000
type: object
required:
- customer_id
title: TopCustomer
description: A top customer with metrics and optional provider details.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
PersonalAccessTokenAuth:
type: http
scheme: bearer
description: >-
Personal access token, sent as `Authorization: Bearer `. Each
operation lists the permission it needs: `read_only` or `full_access`. A
full-access token can call every operation. A read-only token can call
only the operations that list `read_only`; anything else returns 403
`read_only_credential_route_not_allowed`.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.