> ## 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 base price or a selectable market price variant. Variants inherit their base price outside the markets they override. Configure introductory and promotional benefits through Offers.

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


## OpenAPI

````yaml /openapi/en/rest/2026-07-24.json post /plans/{id}/prices
openapi: 3.1.0
info:
  title: Commet API
  version: '2026-07-24'
  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: Markets
    description: >-
      Reusable country groups for market-specific prices and selectable price
      variants.
  - name: Offers
  - 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 base price or a selectable market price variant. Variants inherit
        their base price outside the markets they override. Configure
        introductory and promotional benefits through Offers.
      operationId: add-plan-price
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Unique key used to safely retry this write for 24 hours without
            applying it twice.
          schema:
            type: string
            minLength: 1
            maxLength: 200
        - 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-07-24'
          example: '2026-07-24'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    billingInterval:
                      type: string
                      enum:
                        - weekly
                        - monthly
                        - quarterly
                        - semiannual
                        - yearly
                        - one_time
                    metadata:
                      type: object
                      propertyNames:
                        type: string
                      additionalProperties: {}
                    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'
                    marketPrices:
                      minItems: 1
                      type: array
                      items:
                        type: object
                        properties:
                          marketGroupId:
                            type: string
                            minLength: 1
                            description: Public ID of a reusable pricing market group.
                          currency:
                            type: string
                            enum:
                              - usd
                              - ars
                              - brl
                              - clp
                              - cop
                              - pen
                              - uyu
                              - pyg
                              - bob
                              - mxn
                              - cad
                              - eur
                              - gbp
                              - jpy
                              - cny
                              - krw
                              - hkd
                              - sgd
                              - twd
                              - inr
                              - thb
                            description: >-
                              Presentment currency configured for this plan and
                              market.
                          price:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                            description: Market price in the currency's minor unit.
                        required:
                          - marketGroupId
                          - currency
                          - price
                        additionalProperties: false
                  required:
                    - billingInterval
                    - price
                  additionalProperties: false
                  description: >-
                    A base price. Market prices are optional overrides; currency
                    pricing remains the fallback elsewhere.
                - type: object
                  properties:
                    billingInterval:
                      type: string
                      enum:
                        - weekly
                        - monthly
                        - quarterly
                        - semiannual
                        - yearly
                        - one_time
                    metadata:
                      type: object
                      propertyNames:
                        type: string
                      additionalProperties: {}
                    inheritsFromPriceId:
                      type: string
                      minLength: 1
                    marketPrices:
                      minItems: 1
                      type: array
                      items:
                        type: object
                        properties:
                          marketGroupId:
                            type: string
                            minLength: 1
                            description: Public ID of a reusable pricing market group.
                          currency:
                            type: string
                            enum:
                              - usd
                              - ars
                              - brl
                              - clp
                              - cop
                              - pen
                              - uyu
                              - pyg
                              - bob
                              - mxn
                              - cad
                              - eur
                              - gbp
                              - jpy
                              - cny
                              - krw
                              - hkd
                              - sgd
                              - twd
                              - inr
                              - thb
                            description: >-
                              Presentment currency configured for this plan and
                              market.
                          price:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                            description: Market price in the currency's minor unit.
                        required:
                          - marketGroupId
                          - currency
                          - price
                        additionalProperties: false
                  required:
                    - billingInterval
                    - inheritsFromPriceId
                    - marketPrices
                  additionalProperties: false
                  description: >-
                    A selectable market price variant. It inherits the base
                    terms and must override at least one market already
                    configured on the base price.
      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:
                $ref: '#/components/schemas/PlanPrice'
        '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'
        '403':
          description: Forbidden
          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'
        '409':
          description: Conflict
          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'
        '503':
          description: Service unavailable
          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
          description: Public plan price ID.
        planId:
          type: string
        billingInterval:
          $ref: '#/components/schemas/BillingInterval'
        price:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Price in the currency's minor unit (for example, cents for USD).
        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'
        offerId:
          description: Automatic introductory offer for this price.
          type:
            - string
            - 'null'
        inheritsFromPriceId:
          description: >-
            Public base price ID for a market price variant, or null for a base
            price.
          type:
            - string
            - 'null'
        metadata:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
          description: Application metadata. Variant display names may use metadata.name.
        marketPrices:
          type: array
          items:
            type: object
            properties:
              marketGroupId:
                type: string
                description: Public pricing market group ID.
              currency:
                type: string
                description: Presentment currency for this market.
              price:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: Market price in the currency's minor unit.
            required:
              - marketGroupId
              - currency
              - price
            additionalProperties: false
          description: >-
            Country-market overrides. Variants inherit their base price for
            every market not listed.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        object:
          type: string
          const: plan_price
        livemode:
          type: boolean
      required:
        - id
        - planId
        - billingInterval
        - price
        - isDefault
        - trialDays
        - trialRequiresPaymentMethod
        - includedBalance
        - includedCredits
        - offerId
        - inheritsFromPriceId
        - metadata
        - marketPrices
        - createdAt
        - updatedAt
        - object
        - livemode
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        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:
        - error
      additionalProperties: false
    BillingInterval:
      type: string
      enum:
        - weekly
        - monthly
        - quarterly
        - semiannual
        - yearly
        - one_time
  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.