> ## 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. 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. Publishes a new current version of the plan. New buyers get it; existing subscribers stay on their version until you move them with [Change subscription version](https://commet.co/docs/api-reference/subscriptions/change-subscription-version.md) or [Move subscribers to a plan version](https://commet.co/docs/api-reference/plans/create-plan-move.md). ## OpenAPI ````yaml /openapi/en/rest/2026-08-27.json post /plans/{id}/prices openapi: 3.1.0 info: title: Commet API version: '2026-08-27' 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-08-27' example: '2026-08-27' 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' example: id: price_1a2b3c4d planId: plan_1a2b3c4d billingInterval: monthly price: 2000 isDefault: true trialDays: 0 includedBalance: null includedCredits: null offerId: null inheritsFromPriceId: null metadata: {} marketPrices: [] createdAt: '2026-09-07T12:00:00.000Z' updatedAt: '2026-09-07T12:00:00.000Z' object: plan_price livemode: false '400': description: Bad request headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: validation_error code: validation_error message: The request contains an invalid parameter. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md '401': description: Unauthorized headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: authentication_error code: unauthorized message: A valid API key is required. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md '403': description: Forbidden headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: authentication_error code: forbidden message: You do not have permission to perform this operation. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md '404': description: Not found headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: not_found_error code: not_found message: The requested resource was not found. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md '409': description: Conflict headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: conflict_error code: idempotency_in_progress message: >- A request with this idempotency key is still being processed. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md '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' example: error: type: rate_limit_error code: rate_limited message: >- Too many requests. Retry after the interval specified in the Retry-After header. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md '500': description: Internal server error headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: internal_error code: internal_error message: An unexpected error occurred while processing the request. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md '503': description: Service unavailable headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: internal_error code: idempotency_unavailable message: >- Idempotency storage is temporarily unavailable. Retry with the same idempotency key. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md x-codeSamples: - lang: typescript label: TypeScript source: |- import { Commet } from "@commet/node"; const commet = new Commet({ apiKey: "ck_xxx" }); const planPrice = await commet.plans.addPrice({ id: "pln_xxx", billingInterval: "weekly", price: 1, }); - lang: python label: Python source: |- from commet import Commet commet = Commet("ck_xxx") plan_price = commet.plans.add_price( "pln_xxx", billing_interval="weekly", price=1, ) - lang: go label: Go source: "client, err := commet.New(\"ck_xxx\")\nif err != nil {\n\tlog.Fatal(err)\n}\nctx := context.Background()\n\nplanPrice, err := client.Plans.AddPrice(ctx, \"pln_xxx\", &commet.AddPlanPriceParams{\n\tBillingInterval: \"weekly\",\n\tPrice: func(value int) *int { return &value }(1),\n})\nif err != nil {\n\tlog.Fatal(err)\n}" - lang: java label: Java source: |- import co.commet.Commet; import co.commet.params.AddPlanPriceParams; var commet = Commet.builder().apiKey("ck_xxx").build(); var planPrice = commet.plans().addPrice( "pln_xxx", AddPlanPriceParams.builder("weekly").price(1L).build() ); - lang: php label: PHP source: |- use Commet\Commet; $commet = new Commet('ck_xxx'); $planPrice = $commet->plans->addPrice( id: 'pln_xxx', billingInterval: 'weekly', price: 1, ); 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.