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

# Customer analytics



## OpenAPI

````yaml /v3-beta/api-reference/openapi.yaml get /v3/customers/{id}/analytics
openapi: 3.1.0
info:
  title: Suby.fi Merchant API
  version: 3.0.0-beta
  description: >
    The **v3** public merchant API for Suby.fi. RESTful (plural,
    resource-oriented

    endpoints under the `/v3` prefix). Authenticate every request

    with your secret API key in the `X-Suby-Api-Key` header.


    - `sk_live_…` keys operate in **production** (real funds).

    - `sk_sandbox_…` keys operate in a fully simulated **sandbox** (test cards,
      Base Sepolia crypto, no real money). The environment is derived from the
      key prefix.

    All monetary amounts are **integer cents** (except `priceCents` on some

    read shapes, which is a string) — token amounts are strings in the smallest

    unit (sats / lamports / wei). Fees are basis points.
  contact:
    email: dev@suby.fi
    url: https://suby.fi
servers:
  - url: https://api.beta.suby.fi
    description: Production + sandbox (environment selected by API key prefix)
security:
  - ApiKeyAuth: []
tags:
  - name: Products
    description: Manage your product catalog (one-time and recurring).
  - name: Checkout
    description: >-
      Hosted checkout — signed session tokens (`cs_…`) plus branding and
      appearance settings.
  - name: Payments
    description: >-
      Create, capture, void, and retrieve one-time & off-session payments (card,
      APM, and crypto).
  - name: Subscriptions
    description: Start and cancel recurring subscriptions.
  - name: Customers
    description: First-class customer records with billing address.
  - name: Payment Methods
    description: >-
      Save a payment method to a customer and manage saved instruments for
      off-session charges.
  - name: Webhook Endpoints
    description: Register outbound webhook destinations and rotate signing secrets.
  - name: Analytics
    description: Org-wide revenue analytics.
  - name: Health
    description: Unauthenticated liveness probe.
paths:
  /v3/customers/{id}/analytics:
    get:
      tags:
        - Customers
      summary: Customer analytics
      operationId: getCustomerAnalytics
      parameters:
        - $ref: '#/components/parameters/CustomerId'
        - $ref: '#/components/parameters/StartDate'
        - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: Customer KPIs + revenue trend
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - properties:
                      data:
                        $ref: '#/components/schemas/CustomerAnalytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    CustomerId:
      name: id
      in: path
      required: true
      schema:
        type: string
        example: cus_abc123
    StartDate:
      name: startDate
      in: query
      description: Window start, epoch milliseconds.
      schema:
        type: integer
        minimum: 0
    EndDate:
      name: endDate
      in: query
      description: Window end, epoch milliseconds.
      schema:
        type: integer
        minimum: 0
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        data:
          description: Endpoint-specific payload.
    CustomerAnalytics:
      type: object
      properties:
        currency:
          type: string
        hasCrypto:
          type: boolean
        startDate:
          type: integer
        endDate:
          type: integer
        series:
          type: array
          items:
            $ref: '#/components/schemas/RevenuePoint'
        stats:
          type: object
          properties:
            revenueCents:
              type: integer
            payments:
              type: integer
            refunds:
              type: integer
            refundAmountCents:
              type: integer
            cryptoPct:
              type: number
            cryptoRevenueCents:
              type: integer
            avgPaymentCents:
              type: integer
            lastPaymentAt:
              type: string
              nullable: true
            prevLabel:
              type: string
            revenueDelta:
              type: number
              nullable: true
            paymentsDelta:
              type: number
              nullable: true
    RevenuePoint:
      type: object
      properties:
        date:
          type: string
        full:
          type: string
        unit:
          type: string
          enum:
            - day
            - week
            - month
        fiatCents:
          type: integer
        cryptoCents:
          type: integer
        refundCents:
          type: integer
    Error:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Machine-readable error code.
          example: NOT_FOUND
        message:
          type: string
          example: Resource not found
        data:
          description: Optional error detail.
  responses:
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: UNAUTHORIZED
            message: Invalid or missing API key
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: NOT_FOUND
            message: Resource not found
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Suby-Api-Key
      description: Secret API key. `sk_live_…` (production) or `sk_sandbox_…` (sandbox).

````