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

# Subscription Metrics

> MRR, active and trialing counts, past due, 30-day churn and the renewals due this week — for this business and environment.

The numbers behind a subscriptions dashboard, for the business and environment
the API key belongs to.

## Request authentication

This endpoint requires a **Secret Key** (`sk_...`).

## How MRR is calculated

Every running subscription is normalised to a monthly figure in USD from **its
own terms**, not from its plan — so a subscriber still on last year's price
contributes last year's price.

* A quarterly plan counts a third of its price each month; an annual one a twelfth.
* Amounts in other currencies are converted at the current rate.
* Subscriptions set to cancel at period end are excluded — they are not
  recurring any more.
* `trialing` and `past_due` subscriptions are included: they are still expected
  to pay.

`churn_percent` is subscriptions canceled or expired in the last 30 days over
that number plus the ones still running. It is `null` when there is no base to
measure against, rather than `0` — a new account has not achieved zero churn,
it has no churn to report yet.


## OpenAPI

````yaml GET /subscriptions/summary
openapi: 3.0.0
info:
  title: Creptapay API
  version: 1.0.0
  description: External API endpoints for Creptapay payment processing.
servers:
  - url: https://api.creptapay.com/v1
security: []
paths:
  /subscriptions/summary:
    get:
      tags:
        - Subscriptions
      summary: Subscription Metrics
      description: >-
        MRR, active and trialing counts, past due, 30-day churn and the renewals
        due this week — for this business and environment.
      responses:
        '200':
          description: Portfolio metrics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionSummaryEnvelope'
              example:
                message: Successfully fetched subscription metrics
                data:
                  mrr: 4312.5
                  active: 84
                  trialing: 11
                  past_due:
                    count: 6
                    amount: 294
                  canceled_30d: 5
                  churn_percent: 4.76
                  renewals_this_week:
                    count: 19
                    amount: 931
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    SubscriptionSummaryEnvelope:
      type: object
      description: Subscription metrics.
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/SubscriptionSummary'
    SubscriptionSummary:
      type: object
      description: Portfolio metrics for this business and environment.
      properties:
        mrr:
          type: number
          description: >-
            Monthly recurring revenue in USD. Every subscription is normalised
            from its own terms — a quarterly plan counts a third of its price
            each month, an annual one a twelfth. Subscriptions set to cancel are
            excluded.
        active:
          type: integer
        trialing:
          type: integer
          description: In a trial, or awaiting a first payment.
        past_due:
          type: object
          description: Unpaid but still inside their grace window.
          properties:
            count:
              type: integer
            amount:
              type: number
              description: In USD.
        canceled_30d:
          type: integer
          description: Canceled or expired in the last 30 days.
        churn_percent:
          type: number
          description: >-
            Churned over churned plus running. Null when there is no base to
            measure against.
          nullable: true
        renewals_this_week:
          type: object
          description: Falling due in the next seven days.
          properties:
            count:
              type: integer
            amount:
              type: number
              description: In USD.
    Error:
      type: object
      description: Every failure comes back in this shape. `data` is always null.
      properties:
        message:
          type: string
          description: >-
            What went wrong, in plain words — safe to log, not to show a
            customer verbatim.
        data:
          nullable: true
          example: null
  responses:
    BadRequest:
      description: >-
        The request was rejected — a missing field, a value out of range, or an
        operation that isn't valid for the object's current state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: A grace period can't be longer than 30 days
            data: null
    Unauthorized:
      description: The API key is missing, malformed, or not valid for this environment.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Invalid API key
            data: null
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.