> ## 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

> <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. Requires read access to the app. Customer details are enriched through Stripe. Filter to one currency because amounts across currencies are otherwise summed without conversion. Send both start_date and end_date to set a window. With neither or only one, period selects whole UTC days including today. Results come from an analytics store and can lag behind the payment provider. This is a bounded summary with no cursor to retrieve more rows.



## 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:
  - ApiKeyAuth: []
paths:
  /api/apps/{app_id}/payments/analytics/top-customers:
    get:
      summary: Get top payment customers
      description: >-
        <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. Requires read
        access to the app. Customer details are enriched through Stripe. Filter
        to one currency because amounts across currencies are otherwise summed
        without conversion. Send both start_date and end_date to set a window.
        With neither or only one, period selects whole UTC days including today.
        Results come from an analytics store and can lag behind the payment
        provider. This is a bounded summary with no cursor to retrieve more
        rows.
      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:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            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:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            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:
            anyOf:
              - type: string
              - type: 'null'
            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, or the app does not exist. A
            missing app and an app you cannot reach are deliberately the same
            answer.
        '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'
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:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: Personal API key.

````