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

# List plans

> List all plans with their prices and features. Optionally include private plans.

> [!NOTE]
>
> This reference describes API version `2026-05-18`. Send `Commet-Version: 2026-05-18` with your request.


## OpenAPI

````yaml /openapi/en/rest/2026-05-18.json get /plans
openapi: 3.1.0
info:
  title: Commet API
  version: '2026-05-18'
  description: Billing and payments API for SaaS and AI products.
servers:
  - url: https://commet.co/api/v1
security:
  - ApiKeyAuth: []
tags:
  - name: Test Clock
    description: >-
      Simulate the passage of time in sandbox to test billing flows. Mirrors
      Stripe test clocks: forward-only and sandbox-only.
  - name: Customers
  - name: Subscriptions
  - name: Plans
  - name: Promo Codes
  - name: Features
  - name: Usage
  - name: Seats
  - name: Quota
  - name: Add-ons
  - name: Portal
  - name: Credit Packs
  - name: Plan Groups
  - name: Invoices
  - name: Payments
    description: >-
      One-time payments with no subscription or plan. Charge a customer's saved
      payment method off-session, or create a payment link the customer opens to
      pay. Tax, invoice, and receipt are handled automatically.
  - name: Transactions
  - name: Webhooks
  - name: API Keys
  - name: Payouts
    description: >-
      Withdraw available balance to your bank and manage the payout account
      (verification + destination bank accounts).
  - name: Provisioning
    description: >-
      Take ownership of an organization an agent provisioned headlessly. The
      agent holds the API keys from the start; a human claims the account
      through a claim link.
paths:
  /plans:
    get:
      tags:
        - Plans
      summary: List plans
      description: >-
        List all plans with their prices and features. Optionally include
        private plans.
      operationId: list-plans
      parameters:
        - name: includePrivate
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: Commet-Version
          in: header
          required: false
          description: >-
            API version used by this reference. Send this header to select this
            contract explicitly.
          schema:
            type: string
            default: '2026-05-18'
          example: '2026-05-18'
      responses:
        '200':
          description: Success
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              description: Maximum number of requests allowed in the current window.
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Plan'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              description: Maximum number of requests allowed in the current window.
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: string
            RateLimit-Reset:
              description: Seconds until the rate limit window resets.
              schema:
                type: string
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  headers:
    RequestId:
      description: >-
        Server-generated identifier that correlates this response with Platform
        logs.
      schema:
        type: string
        format: uuid
  schemas:
    Plan:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        code:
          type: string
        description:
          type:
            - string
            - 'null'
        consumptionModel:
          anyOf:
            - type: string
              enum:
                - metered
                - credits
                - balance
            - type: 'null'
        isPublic:
          type: boolean
        isDefault:
          type: boolean
        isFree:
          type: boolean
        blockOnExhaustion:
          description: >-
            Credits and balance plans: true stops usage when the plan and
            purchased amounts run out; false lets usage continue and bills the
            missing amount as overage at the next renewal (credits at the price
            per credit). Trials and free plans always stop.
          type:
            - boolean
            - 'null'
        unusedPlanCredits:
          anyOf:
            - oneOf:
                - type: object
                  properties:
                    type:
                      type: string
                      const: expire
                  required:
                    - type
                  additionalProperties: false
                  description: >-
                    Each reset replaces unused plan credits with the price's
                    included credits.
                - type: object
                  properties:
                    type:
                      type: string
                      const: roll_over
                    maxPlanCredits:
                      anyOf:
                        - type: integer
                          exclusiveMinimum: 0
                          maximum: 2147483647
                        - type: 'null'
                      description: >-
                        The most plan credits a subscription holds after a
                        reset, including the credits that reset grants; credits
                        above it expire. At least the included credits of every
                        price. null means no limit other than the largest
                        storable balance, 2,147,483,647 plan credits.
                  required:
                    - type
                    - maxPlanCredits
                  additionalProperties: false
                  description: >-
                    Unused plan credits roll over: each reset adds the price's
                    included credits to them.
              description: >-
                What happens to unused plan credits at each reset, including the
                reset of a subscription that changes to this plan. Purchased
                credits never expire and never count toward maxPlanCredits.
                Changing it publishes a new version of the plan; each
                subscription stays on its version until moved.
            - type: 'null'
          description: >-
            Credits plans only; null for other consumption models. What happens
            to unused plan credits at each reset. Purchased credits never expire
            and never count toward maxPlanCredits.
        planCreditLimit:
          anyOf:
            - type: object
              properties:
                credits:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 2147483647
                  description: The most plan credits a subscription spends in one window.
                interval:
                  type: string
                  enum:
                    - day
                    - week
                  description: >-
                    The window length: `day` is 24 hours and `week` is 7 days,
                    starting at the time of day of the subscription's billing
                    anchor.
              required:
                - credits
                - interval
              additionalProperties: false
              description: >-
                Caps how many plan credits a subscription spends per window.
                Purchased credits are never limited: usage past the limit draws
                from them. Changing it publishes a new version of the plan; each
                subscription stays on its version until moved.
            - type: 'null'
          description: >-
            Credits plans only. The most plan credits a subscription spends per
            day or per week; null means no limit.
        unusedPlanBalance:
          anyOf:
            - oneOf:
                - type: object
                  properties:
                    type:
                      type: string
                      const: expire
                  required:
                    - type
                  additionalProperties: false
                  description: >-
                    Each reset replaces unused plan balance with the price's
                    included balance.
                - type: object
                  properties:
                    type:
                      type: string
                      const: roll_over
                    maxPlanBalance:
                      anyOf:
                        - type: integer
                          exclusiveMinimum: 0
                          maximum: 2147483647
                        - type: 'null'
                      description: >-
                        The most plan balance a subscription holds after a
                        reset, in USD cents, including the balance that reset
                        grants; balance above it expires. At least the included
                        balance of every price. Other currencies convert it with
                        the plan's exchange rate unless the dashboard sets a
                        custom amount for that currency. null means no limit
                        other than the largest storable amount, 2,147,483,647
                        cents.
                  required:
                    - type
                    - maxPlanBalance
                  additionalProperties: false
                  description: >-
                    Unused plan balance rolls over: each reset adds the price's
                    included balance to it.
              description: >-
                What happens to unused plan balance at each reset, including the
                reset of a subscription that changes to this plan. Purchased
                balance never expires and never counts toward maxPlanBalance.
                Changing it publishes a new version of the plan; each
                subscription stays on its version until moved.
            - type: 'null'
          description: >-
            Balance plans only; null for other consumption models. What happens
            to unused plan balance at each reset. Purchased balance never
            expires and never counts toward maxPlanBalance.
        planBalanceLimit:
          anyOf:
            - type: object
              properties:
                amount:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 2147483647
                  description: >-
                    The most plan balance a subscription spends in one window,
                    in USD cents. Other currencies convert it with the plan's
                    exchange rate unless the dashboard sets a custom amount for
                    that currency.
                interval:
                  type: string
                  enum:
                    - day
                    - week
                  description: >-
                    The window length: `day` is 24 hours and `week` is 7 days,
                    starting at the time of day of the subscription's billing
                    anchor.
              required:
                - amount
                - interval
              additionalProperties: false
              description: >-
                Caps how much plan balance a subscription spends per window.
                Purchased balance is never limited: usage past the limit draws
                from it. Changing it publishes a new version of the plan; each
                subscription stays on its version until moved.
            - type: 'null'
          description: >-
            Balance plans only. The most plan balance a subscription spends per
            day or per week, in USD cents; null means no limit.
        sortOrder:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        planGroupId:
          type:
            - string
            - 'null'
        metadata:
          anyOf:
            - type: object
              propertyNames:
                type: string
              additionalProperties: {}
            - type: 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        features:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              name:
                type: string
              type:
                type: string
                enum:
                  - boolean
                  - usage
                  - seats
                  - quota
              unitName:
                type:
                  - string
                  - 'null'
              enabled:
                type: boolean
              includedAmount:
                anyOf:
                  - type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  - type: 'null'
              unlimited:
                type: boolean
              overage:
                anyOf:
                  - type: object
                    properties:
                      enabled:
                        type: boolean
                      model:
                        anyOf:
                          - type: string
                            enum:
                              - per_unit
                          - type: 'null'
                      unitPrice:
                        anyOf:
                          - type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                          - type: 'null'
                    required:
                      - enabled
                      - model
                      - unitPrice
                    additionalProperties: false
                  - type: 'null'
              regionalPrices:
                type: array
                items:
                  type: object
                  properties:
                    currency:
                      type: string
                    overageUnitPrice:
                      anyOf:
                        - type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                        - type: 'null'
                    autoSynced:
                      type: boolean
                  required:
                    - currency
                    - overageUnitPrice
                    - autoSynced
                  additionalProperties: false
              overageEnabled:
                type: boolean
              overageUnitPrice:
                anyOf:
                  - type: integer
                  - type: 'null'
            required:
              - code
              - name
              - type
              - unitName
              - enabled
              - includedAmount
              - unlimited
              - overage
              - overageEnabled
              - overageUnitPrice
            additionalProperties: false
        prices:
          type: array
          items:
            type: object
            properties:
              billingInterval:
                type: string
                enum:
                  - weekly
                  - monthly
                  - quarterly
                  - semiannual
                  - yearly
                  - one_time
              price:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              isDefault:
                type: boolean
              trialDays:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              trialRequiresPaymentMethod:
                description: >-
                  Whether the price's free trial needs a payment method to
                  start. When false, a new subscription starts trialing right
                  away without checkout; without a payment method added by the
                  trial end, the customer moves to the plan group's default
                  plan, or the subscription is canceled when there is none. Null
                  when the price has no trial.
                type:
                  - boolean
                  - 'null'
              includedBalance:
                anyOf:
                  - type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  - type: 'null'
              includedCredits:
                anyOf:
                  - type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  - type: 'null'
              introOffer:
                anyOf:
                  - type: object
                    properties:
                      enabled:
                        type: boolean
                      discountType:
                        anyOf:
                          - type: string
                            enum:
                              - percentage
                              - amount
                          - type: 'null'
                      discountValue:
                        anyOf:
                          - type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                          - type: 'null'
                      durationCycles:
                        anyOf:
                          - type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                          - type: 'null'
                    required:
                      - enabled
                      - discountType
                      - discountValue
                      - durationCycles
                    additionalProperties: false
                  - type: 'null'
              regionalPrices:
                type: array
                items:
                  type: object
                  properties:
                    currency:
                      type: string
                    price:
                      type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                    includedBalance:
                      anyOf:
                        - type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                        - type: 'null'
                    autoSynced:
                      type: boolean
                  required:
                    - currency
                    - price
                    - includedBalance
                    - autoSynced
                  additionalProperties: false
            required:
              - billingInterval
              - price
              - isDefault
              - trialDays
              - trialRequiresPaymentMethod
              - includedBalance
              - includedCredits
              - introOffer
            additionalProperties: false
        exchangeRates:
          type: array
          items:
            type: object
            properties:
              currency:
                type: string
              exchangeRate:
                type: number
            required:
              - currency
              - exchangeRate
            additionalProperties: false
      required:
        - id
        - name
        - code
        - description
        - consumptionModel
        - isPublic
        - isDefault
        - isFree
        - blockOnExhaustion
        - unusedPlanCredits
        - planCreditLimit
        - unusedPlanBalance
        - planBalanceLimit
        - sortOrder
        - planGroupId
        - metadata
        - createdAt
        - updatedAt
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        success:
          const: false
        code:
          type: string
        message:
          type: string
        details: {}
      required:
        - success
        - code
        - message
  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.