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

# Top up balance

> Top up a balance subscription. Creates the top-up invoice and charges the customer's payment method for the amount plus tax. Once the payment is confirmed, adds the amount to the subscription's purchased balance (after paying back any overage owed on the plan balance), marks the invoice paid and emits `balance.topped_up`. Purchased balance is spent after the plan balance and is kept until the subscription ends. Rejected with 400 when the subscription is not on a balance plan, its plan has top-ups turned off, or the amount is below the effective minimum: the plan's minimum top-up in the subscription currency, raised to the currency's minimum charge.

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


## OpenAPI

````yaml /openapi/en/rest/2026-06-10.json post /subscriptions/{id}/balance/topup
openapi: 3.1.0
info:
  title: Commet API
  version: '2026-06-10'
  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:
  /subscriptions/{id}/balance/topup:
    post:
      tags:
        - Subscriptions
      summary: Top up balance
      description: >-
        Top up a balance subscription. Creates the top-up invoice and charges
        the customer's payment method for the amount plus tax. Once the payment
        is confirmed, adds the amount to the subscription's purchased balance
        (after paying back any overage owed on the plan balance), marks the
        invoice paid and emits `balance.topped_up`. Purchased balance is spent
        after the plan balance and is kept until the subscription ends. Rejected
        with 400 when the subscription is not on a balance plan, its plan has
        top-ups turned off, or the amount is below the effective minimum: the
        plan's minimum top-up in the subscription currency, raised to the
        currency's minimum charge.
      operationId: topup-balance
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - 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-06-10'
          example: '2026-06-10'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                  description: >-
                    The amount to add, in minor units of the subscription
                    currency (cents; whole units for zero-decimal currencies).
              required:
                - amount
              additionalProperties: false
      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:
                    $ref: '#/components/schemas/BalanceTopup'
                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'
        '402':
          description: Payment required
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          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:
    BalanceTopup:
      type: object
      properties:
        amount:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        status:
          type: string
          enum:
            - succeeded
            - processing
          description: >-
            `succeeded` when the payment was confirmed and the balance was
            added. `processing` when the payment method confirms later: the
            balance is added once the payment is confirmed, and nothing is added
            if it is declined.
        object:
          type: string
          const: subscription
        livemode:
          type: boolean
      required:
        - amount
        - status
        - object
        - livemode
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
            param:
              type: string
            details: {}
            doc_url:
              type: string
          required:
            - type
            - code
            - message
            - doc_url
          additionalProperties: false
      required:
        - success
        - error
      additionalProperties: false
  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.