> ## 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. # Change plan > Upgrade or change billing interval immediately, optionally applying an Offer. Scheduled changes do not accept offers. Upgrade or change billing interval immediately, optionally applying an Offer. Scheduled changes do not accept offers. ## OpenAPI ````yaml /openapi/es/rest/2026-08-27.json post /subscriptions/{id}/change-plan 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: /subscriptions/{id}/change-plan: post: tags: - Subscriptions summary: Change plan description: >- Upgrade or change billing interval immediately, optionally applying an Offer. Scheduled changes do not accept offers. operationId: change-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: 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: newPlanId: type: string minLength: 1 newBillingInterval: type: string enum: - weekly - monthly - quarterly - yearly successUrl: type: string format: uri offerId: type: string minLength: 1 responses: '200': 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/PlanChange' example: outcome: requires_checkout requiresCheckout: true checkoutUrl: https://commet.co/checkout/example_plan_change_token object: plan_change 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 '402': description: Payment required headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: billing_error code: payment_failed message: The payment could not be completed. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/payment_failed.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 planChange = await commet.subscriptions.changePlan({ id: "sub_xxx" }); - lang: python label: Python source: |- from commet import Commet commet = Commet("ck_xxx") plan_change = commet.subscriptions.change_plan("sub_xxx") - lang: go label: Go source: "client, err := commet.New(\"ck_xxx\")\nif err != nil {\n\tlog.Fatal(err)\n}\nctx := context.Background()\n\nplanChange, err := client.Subscriptions.ChangePlan(ctx, \"sub_xxx\", nil)\nif err != nil {\n\tlog.Fatal(err)\n}" - lang: java label: Java source: |- import co.commet.Commet; import co.commet.params.ChangePlanParams; var commet = Commet.builder().apiKey("ck_xxx").build(); var planChange = commet.subscriptions().changePlan( "sub_xxx", ChangePlanParams.builder().build() ); - lang: php label: PHP source: |- use Commet\Commet; $commet = new Commet('ck_xxx'); $planChange = $commet->subscriptions->changePlan(id: 'sub_xxx'); components: headers: RequestId: description: >- Server-generated identifier that correlates this response with Platform logs. schema: type: string format: uuid schemas: PlanChange: oneOf: - type: object properties: outcome: type: string const: requires_checkout requiresCheckout: type: boolean const: true checkoutUrl: type: string offerApplication: type: object properties: id: type: string offerId: type: string name: type: string currency: type: string subtotal: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Subtotal in the currency's minor unit. discountAmount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Discount in the currency's minor unit. total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Total in the currency's minor unit. phases: minItems: 1 type: array items: oneOf: - type: object properties: type: type: string const: free_trial durationDays: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 startsAt: anyOf: - type: string format: date-time - type: 'null' endsAt: anyOf: - type: string format: date-time - type: 'null' required: - type - durationDays - startsAt - endsAt additionalProperties: false - type: object properties: type: type: string const: percentage durationCycles: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' durationInterval: anyOf: - type: string enum: - weekly - monthly - quarterly - yearly - type: 'null' startsAt: anyOf: - type: string format: date-time - type: 'null' endsAt: anyOf: - type: string format: date-time - type: 'null' percentage: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 description: Discount in basis points. 5000 means 50%. required: - type - durationCycles - durationInterval - startsAt - endsAt - percentage additionalProperties: false - type: object properties: type: type: string const: amount_off durationCycles: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' durationInterval: anyOf: - type: string enum: - weekly - monthly - quarterly - yearly - type: 'null' startsAt: anyOf: - type: string format: date-time - type: 'null' endsAt: anyOf: - type: string format: date-time - type: 'null' amount: type: integer minimum: 0 maximum: 9007199254740991 description: Discount in the application currency's minor unit. required: - type - durationCycles - durationInterval - startsAt - endsAt - amount additionalProperties: false - type: object properties: type: type: string const: fixed_price durationCycles: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' durationInterval: anyOf: - type: string enum: - weekly - monthly - quarterly - yearly - type: 'null' startsAt: anyOf: - type: string format: date-time - type: 'null' endsAt: anyOf: - type: string format: date-time - type: 'null' price: type: integer minimum: 0 maximum: 9007199254740991 description: >- Fixed price in the application currency's minor unit. required: - type - durationCycles - durationInterval - startsAt - endsAt - price additionalProperties: false appliesTo: oneOf: - type: object properties: type: type: string const: plan_price id: type: string required: - type - id additionalProperties: false - type: object properties: type: type: string const: addon id: type: string required: - type - id additionalProperties: false - type: object properties: type: type: string const: credit_pack id: type: string required: - type - id additionalProperties: false required: - id - offerId - name - currency - subtotal - discountAmount - total - phases - appliesTo additionalProperties: false object: type: string const: plan_change livemode: type: boolean required: - outcome - requiresCheckout - checkoutUrl - object - livemode additionalProperties: false - type: object properties: outcome: type: string const: scheduled id: type: string scheduled: type: boolean const: true scheduledFor: type: string format: date-time changeType: type: string enum: - subscription.plan_downgrade - subscription.interval_change - subscription.cancel customerId: type: string newPlanId: type: string newPlanName: type: string newBillingInterval: type: string seatLimitWarning: type: object properties: featureCode: type: string featureName: type: string currentSeats: type: integer minimum: -9007199254740991 maximum: 9007199254740991 included: type: integer minimum: -9007199254740991 maximum: 9007199254740991 newPlanName: type: string effectiveDate: type: string format: date-time required: - featureCode - featureName - currentSeats - included - newPlanName - effectiveDate additionalProperties: false object: type: string const: plan_change livemode: type: boolean required: - outcome - id - scheduled - scheduledFor - changeType - customerId - object - livemode additionalProperties: false - type: object properties: outcome: type: string const: completed id: type: string scheduled: type: boolean const: false customerId: type: string previousPlan: type: object properties: id: type: string name: type: string required: - id - name additionalProperties: false currentPlan: type: object properties: id: type: string name: type: string price: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - name - price additionalProperties: false billingInterval: type: string billing: type: object properties: credit: type: integer minimum: -9007199254740991 maximum: 9007199254740991 creditsApplied: type: integer minimum: -9007199254740991 maximum: 9007199254740991 charge: type: integer minimum: -9007199254740991 maximum: 9007199254740991 taxAmount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 netAmount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 totalCharged: type: integer minimum: -9007199254740991 maximum: 9007199254740991 remainingCreditBalance: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - credit - creditsApplied - charge - taxAmount - netAmount - totalCharged - remainingCreditBalance additionalProperties: false invoiceId: type: string offerApplication: type: object properties: id: type: string offerId: type: string name: type: string currency: type: string subtotal: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Subtotal in the currency's minor unit. discountAmount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Discount in the currency's minor unit. total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Total in the currency's minor unit. phases: minItems: 1 type: array items: oneOf: - type: object properties: type: type: string const: free_trial durationDays: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 startsAt: anyOf: - type: string format: date-time - type: 'null' endsAt: anyOf: - type: string format: date-time - type: 'null' required: - type - durationDays - startsAt - endsAt additionalProperties: false - type: object properties: type: type: string const: percentage durationCycles: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' durationInterval: anyOf: - type: string enum: - weekly - monthly - quarterly - yearly - type: 'null' startsAt: anyOf: - type: string format: date-time - type: 'null' endsAt: anyOf: - type: string format: date-time - type: 'null' percentage: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 description: Discount in basis points. 5000 means 50%. required: - type - durationCycles - durationInterval - startsAt - endsAt - percentage additionalProperties: false - type: object properties: type: type: string const: amount_off durationCycles: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' durationInterval: anyOf: - type: string enum: - weekly - monthly - quarterly - yearly - type: 'null' startsAt: anyOf: - type: string format: date-time - type: 'null' endsAt: anyOf: - type: string format: date-time - type: 'null' amount: type: integer minimum: 0 maximum: 9007199254740991 description: Discount in the application currency's minor unit. required: - type - durationCycles - durationInterval - startsAt - endsAt - amount additionalProperties: false - type: object properties: type: type: string const: fixed_price durationCycles: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' durationInterval: anyOf: - type: string enum: - weekly - monthly - quarterly - yearly - type: 'null' startsAt: anyOf: - type: string format: date-time - type: 'null' endsAt: anyOf: - type: string format: date-time - type: 'null' price: type: integer minimum: 0 maximum: 9007199254740991 description: >- Fixed price in the application currency's minor unit. required: - type - durationCycles - durationInterval - startsAt - endsAt - price additionalProperties: false appliesTo: oneOf: - type: object properties: type: type: string const: plan_price id: type: string required: - type - id additionalProperties: false - type: object properties: type: type: string const: addon id: type: string required: - type - id additionalProperties: false - type: object properties: type: type: string const: credit_pack id: type: string required: - type - id additionalProperties: false required: - id - offerId - name - currency - subtotal - discountAmount - total - phases - appliesTo additionalProperties: false object: type: string const: plan_change livemode: type: boolean required: - outcome - id - scheduled - customerId - previousPlan - currentPlan - billingInterval - billing - 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 ```` ## Related topics - [Preview plan change](/docs/es/api-reference/subscriptions/preview-change-plan.md) - [plan_change_scheduled](/docs/es/api-reference/errors/plan_change_scheduled.md) - [trial.converted](/docs/es/webhooks/trial-converted.md) - [subscription.plan_change_scheduled](/docs/es/webhooks/subscription-plan-change-scheduled.md) - [subscription.plan_change_revoked](/docs/es/webhooks/subscription-plan-change-revoked.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.