> ## 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. # Create plan > Create a new plan with optional consumption model, visibility, and plan group assignment. Create a new plan with optional consumption model, visibility, and plan group assignment. ## OpenAPI ````yaml /openapi/en/rest/2026-08-27.json post /plans 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: post: tags: - Plans summary: Create plan description: >- Create a new plan with optional consumption model, visibility, plan group assignment, overage behavior, and the rollover and spend limit of its plan credits or plan balance. operationId: create-plan 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: 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: type: object properties: name: type: string minLength: 1 code: type: string minLength: 1 pattern: ^[a-z0-9_]+$ description: type: string consumptionModel: type: string enum: - metered - credits - balance isPublic: type: boolean isFree: type: boolean blockOnExhaustion: description: >- Credits and balance plans. Omitted, credits plans and free plans stop usage when the plan and purchased amounts run out, and paid balance plans bill the missing balance as overage. A new credits plan always stops usage: it allows overage only with a price per credit, which is set after creation, and then `PATCH /v1/plans/{id}` turns overage on. type: boolean unusedPlanCredits: description: >- Credits plans only. What happens to unused plan credits at each reset; omitted means they expire. oneOf: - type: object properties: type: type: string const: expire required: - type 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 description: >- Unused plan credits roll over: each reset adds the price's included credits to them. planCreditLimit: description: >- Credits plans only. The most plan credits a subscription spends per day or per week; omitted or null means no limit. 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 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' unusedPlanBalance: description: >- Balance plans only. What happens to unused plan balance at each reset; omitted means it expires. oneOf: - type: object properties: type: type: string const: expire required: - type 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 description: >- Unused plan balance rolls over: each reset adds the price's included balance to it. planBalanceLimit: description: >- Balance plans only. The most plan balance a subscription spends per day or per week, in USD cents; omitted or null means no limit. 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 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' planGroupId: type: string isDefault: description: >- Make this plan the default plan of its plan group: customers created with that planGroupId start on it, and a paid plan of the group that ends from the customer portal, a revoked payment authorization or exhausted dunning moves to it instead of canceling. Requires a free plan with a planGroupId; replaces the group's previous default plan. type: boolean metadata: type: object propertyNames: type: string additionalProperties: {} required: - name - code 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/Plan' example: id: plan_1a2b3c4d name: Pro code: pro description: For growing API products consumptionModel: metered isPublic: true isDefault: false isFree: false blockOnExhaustion: true sortOrder: 0 planGroupId: group_1a2b3c4d metadata: {} createdAt: '2026-09-07T12:00:00.000Z' updatedAt: '2026-09-07T12:00:00.000Z' features: - code: api_calls name: API Calls type: usage unitName: calls enabled: true includedAmount: 1000 unlimited: false overage: enabled: false model: null unitPrice: null regionalPrices: [] prices: - id: price_1a2b3c4d billingInterval: monthly price: 2000 isDefault: true trialDays: 0 includedBalance: null includedCredits: null offerId: null inheritsFromPriceId: null metadata: {} marketPrices: [] regionalPrices: [] exchangeRates: [] object: plan 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 plan = await commet.plans.create({ name: "example", code: "api_calls", }); - lang: python label: Python source: |- from commet import Commet commet = Commet("ck_xxx") plan = commet.plans.create( name="example", code="api_calls", ) - lang: go label: Go source: "client, err := commet.New(\"ck_xxx\")\nif err != nil {\n\tlog.Fatal(err)\n}\nctx := context.Background()\n\nplan, err := client.Plans.Create(ctx, &commet.CreatePlanParams{\n\tName: \"example\",\n\tCode: \"api_calls\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}" - lang: java label: Java source: |- import co.commet.Commet; import co.commet.params.CreatePlanParams; var commet = Commet.builder().apiKey("ck_xxx").build(); var plan = commet.plans().create( CreatePlanParams.builder("example", "api_calls").build() ); - lang: php label: PHP source: |- use Commet\Commet; $commet = new Commet('ck_xxx'); $plan = $commet->plans->create( name: 'example', code: 'api_calls', ); 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: - $ref: '#/components/schemas/ConsumptionModel' - 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: $ref: '#/components/schemas/FeatureType' 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 required: - code - name - type - unitName - enabled - includedAmount - unlimited - overage - regionalPrices additionalProperties: false prices: type: array items: type: object properties: id: type: string description: Public plan price ID. 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. Pass a Promotional Offer ID when creating a subscription to override it. 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. An empty array means currency pricing and then the global USD price remain the fallback. 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: - id - billingInterval - price - isDefault - trialDays - trialRequiresPaymentMethod - includedBalance - includedCredits - offerId - inheritsFromPriceId - metadata - marketPrices - regionalPrices additionalProperties: false exchangeRates: type: array items: type: object properties: currency: type: string exchangeRate: type: number required: - currency - exchangeRate additionalProperties: false countries: type: array items: type: object properties: country: type: string description: ISO country code. currency: type: string description: The currency buyers from the country pay, USD included. prices: type: array items: type: object properties: billingInterval: $ref: '#/components/schemas/BillingInterval' price: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: The country's price in the currency's minor unit. manual: type: boolean description: >- True when set by hand; false when it follows the USD base at the exchange rate. required: - billingInterval - price - manual additionalProperties: false addons: type: array items: type: object properties: addonId: type: string price: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- What buyers from the country pay for the add-on, in the currency's minor unit. manual: type: boolean description: >- True when set by hand; false when it follows the add-on's USD price at the exchange rate. required: - addonId - price - manual additionalProperties: false description: Every add-on the version sells, priced for the country. creditPacks: type: array items: type: object properties: creditPackId: type: string price: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- What buyers from the country pay for the pack, in the currency's minor unit. manual: type: boolean description: >- True when set by hand; false when it follows the pack's USD price at the exchange rate. required: - creditPackId - price - manual additionalProperties: false description: Every credit pack the version sells, priced for the country. required: - country - currency - prices - addons - creditPacks additionalProperties: false description: >- Countries with their own currency or prices in the current version. Buyers from any other country pay the USD prices. object: type: string const: plan livemode: type: boolean required: - id - name - code - description - consumptionModel - isPublic - isDefault - isFree - blockOnExhaustion - unusedPlanCredits - planCreditLimit - unusedPlanBalance - planBalanceLimit - sortOrder - planGroupId - metadata - createdAt - updatedAt - features - prices - exchangeRates - countries - 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 ConsumptionModel: type: string enum: - metered - credits - balance FeatureType: type: string enum: - boolean - usage - seats - quota 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.