> ## 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 experiment > Start an experiment from the plan's current version with the changes given. It is sold only through its own code, sent as planCode after the plan's code; new buyers of the plan keep getting the current version. Start an experiment from the plan's current version with the changes given. It is sold only through its own code, sent as planCode after the plan's code; new buyers of the plan keep getting the current version. Sell it by creating subscriptions with `planCode` set to `:`. The experiment code is never reused in the plan. ## OpenAPI ````yaml /openapi/es/rest/2026-08-27.json post /plans/{id}/experiments 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}/experiments: post: tags: - Plans summary: Create plan experiment description: >- Start an experiment from the plan's current version with the changes given. It is sold only through its code (planCode `:`); new buyers of the plan keep getting the current version. operationId: create-plan-experiment 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: type: object properties: prices: default: [] type: array items: type: object properties: billingInterval: type: string enum: - weekly - monthly - quarterly - semiannual - yearly - one_time description: >- An interval the plan already sells. Prices not listed are copied unchanged from the current version. price: type: integer minimum: 0 maximum: 9007199254740991 description: USD price in the currency's minor unit (cents). includedCredits: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' includedBalance: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' regionalPrices: description: >- Per-currency amounts. A currency the current version does not sell also needs its exchangeRate in currencies; its amounts not listed here are derived from the USD price. type: array items: type: object properties: currency: type: string price: type: integer minimum: 0 maximum: 9007199254740991 includedBalance: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' required: - currency - price required: - billingInterval - price currencies: default: [] description: >- Currencies the current version does not sell, with the exchange rate (local units per USD) used for the amounts not listed, credit purchases, add-ons and overage. type: array items: type: object properties: currency: type: string exchangeRate: type: number exclusiveMinimum: 0 required: - currency - exchangeRate maxPlanCredits: description: >- Credits plans that roll over unused credits: the most plan credits a subscription can hold. Null removes the cap. anyOf: - type: integer minimum: 1 maximum: 2147483647 - type: 'null' maxPlanBalance: description: >- Balance plans that roll over unused balance: the most plan balance a subscription can hold, in USD cents. Other currencies convert it with the plan's exchange rate unless the dashboard sets a custom amount for that currency. Null removes the cap. anyOf: - type: integer minimum: 1 maximum: 2147483647 - type: 'null' code: type: string description: >- The experiment's own code: lowercase letters, numbers, hyphens and underscores. It is sold as planCode `:` and is never reused in the plan. required: - 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/PlanExperiment' example: id: pex_1a2b3c4d code: pro:price-test status: running startedFromVersionId: plr_5e6f7g8h latestVersionId: plr_1a2b3c4d sellsVersionId: plr_1a2b3c4d subscriptionCount: 0 createdAt: '2026-09-07T12:00:00.000Z' closedAt: null object: plan_experiment '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 components: headers: RequestId: description: >- Server-generated identifier that correlates this response with Platform logs. schema: type: string format: uuid schemas: PlanExperiment: type: object properties: id: type: string description: Public plan experiment ID. code: type: string description: >- The code to sell it with as planCode, such as pro:price-test. It always sells the experiment's latest version while running, and the plan's current version once closed. status: type: string enum: - running - won - archived description: >- running sells its latest version; won became the plan's current version; archived stopped selling. startedFromVersionId: type: string description: The plan's version that was current when it started. latestVersionId: type: string description: Its latest version. sellsVersionId: type: string description: The version its code sells to new buyers today. subscriptionCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Active, trialing, past due and paused subscriptions on its versions. createdAt: type: string format: date-time closedAt: anyOf: - type: string format: date-time - type: 'null' object: type: string const: plan_experiment livemode: type: boolean required: - id - code - status - startedFromVersionId - latestVersionId - sellsVersionId - subscriptionCount - createdAt - closedAt - 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 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.