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

# Add price to plan

> Add a billing interval price to a plan with optional trial days and included balance/credits.

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


## OpenAPI

````yaml /openapi/en/rest/2026-05-01.json post /plans/{id}/prices
openapi: 3.1.0
info:
  title: Commet API
  version: '2026-05-01'
  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/{id}/prices:
    post:
      tags:
        - Plans
      summary: Add price to plan
      description: >-
        Add a billing interval price to a plan with optional trial days and
        included balance/credits.
      operationId: add-plan-price
      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-05-01'
          example: '2026-05-01'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                billingInterval:
                  type: string
                  enum:
                    - weekly
                    - monthly
                    - quarterly
                    - semiannual
                    - yearly
                    - one_time
                price:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                trialDays:
                  type: integer
                  minimum: 0
                  maximum: 730
                trialRequiresPaymentMethod:
                  description: >-
                    Set to false so the price's free trial starts without a
                    payment method. Requires trialDays on the price.
                  type: boolean
                isDefault:
                  type: boolean
                includedBalance:
                  anyOf:
                    - type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                    - type: 'null'
                includedCredits:
                  anyOf:
                    - type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                    - type: 'null'
                introOfferEnabled:
                  type: boolean
                introOfferDiscountType:
                  anyOf:
                    - type: string
                      enum:
                        - percentage
                        - amount
                    - type: 'null'
                introOfferDiscountValue:
                  anyOf:
                    - type: integer
                    - type: 'null'
                introOfferDurationCycles:
                  anyOf:
                    - type: integer
                    - type: 'null'
              required:
                - billingInterval
                - price
                - introOfferEnabled
              additionalProperties: false
      responses:
        '201':
          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/PlanPrice'
                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'
        '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:
    PlanPrice:
      type: object
      properties:
        id:
          type: string
        planId:
          type: string
        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'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        introOfferEnabled:
          type: boolean
        introOfferDiscountType:
          anyOf:
            - type: string
              enum:
                - percentage
                - amount
            - type: 'null'
        introOfferDiscountValue:
          anyOf:
            - type: integer
            - type: 'null'
        introOfferDurationCycles:
          anyOf:
            - type: integer
            - type: 'null'
      required:
        - id
        - planId
        - billingInterval
        - price
        - isDefault
        - trialDays
        - trialRequiresPaymentMethod
        - includedBalance
        - includedCredits
        - createdAt
        - updatedAt
        - introOfferEnabled
        - introOfferDiscountType
        - introOfferDiscountValue
        - introOfferDurationCycles
      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.