> ## 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. # Preview plan change > Preview proration details for an immediate plan change without applying it. Free-to-paid changes are never scheduled and the change-plan endpoint always returns hosted checkout for them. For paid plans, interval direction takes precedence: a longer interval is immediate and a shorter interval is scheduled. When the interval is unchanged, a higher-sort-order plan is immediate and a lower-sort-order plan is scheduled. A paid-to-free change is always scheduled. Returns credit, charge, and net amount. The target plan must belong to the same plan group as the current plan, otherwise a 400 with code `plans_not_in_same_group` is returned. A change between two free plans has nothing to prorate and returns a zero-amount estimate. Scheduled changes return a 400 with code `plan_change_scheduled`; apply those via the change-plan endpoint. Pass offerId to quote the destination plan with an Offer. Preview proration details for an immediate plan change without applying it. Free-to-paid changes are never scheduled and the change-plan endpoint always returns hosted checkout for them. For paid plans, interval direction takes precedence: a longer interval is immediate and a shorter interval is scheduled. When the interval is unchanged, a higher-sort-order plan is immediate and a lower-sort-order plan is scheduled. A paid-to-free change is always scheduled. Returns credit, charge, and net amount. The target plan must belong to the same plan group as the current plan, otherwise a 400 with code `plans_not_in_same_group` is returned. A change between two free plans has nothing to prorate and returns a zero-amount estimate. Scheduled changes return a 400 with code `plan_change_scheduled`; apply those via the change-plan endpoint. Pass offerId to quote the destination plan with an Offer. ## OpenAPI ````yaml /openapi/es/rest/2026-08-27.json post /subscriptions/{id}/preview-change 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}/preview-change: post: tags: - Subscriptions summary: Preview plan change description: >- Preview proration details for an immediate plan change without applying it. Free-to-paid changes are never scheduled and the change-plan endpoint always returns hosted checkout for them. For paid plans, interval direction takes precedence: a longer interval is immediate and a shorter interval is scheduled. When the interval is unchanged, a higher-sort-order plan is immediate and a lower-sort-order plan is scheduled. A paid-to-free change is always scheduled. Returns credit, charge, and net amount. The target plan must belong to the same plan group as the current plan, otherwise a 400 with code `plans_not_in_same_group` is returned. A change between two free plans has nothing to prorate and returns a zero-amount estimate. Scheduled changes return a 400 with code `plan_change_scheduled`; apply those via the change-plan endpoint. Pass offerId to quote the destination plan with an Offer. operationId: preview-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: planId: type: string minLength: 1 billingInterval: type: string enum: - weekly - monthly - quarterly - yearly - one_time offerId: type: string minLength: 1 required: - planId 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/PreviewChange' example: currency: usd currentPlanCredit: 2000 newPlanCharge: 4000 estimatedTotal: 2000 effectiveDate: '2026-09-07T12:00:00.000Z' daysRemaining: 30 totalDays: 30 isUpgrade: true object: plan_change_preview 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 previewChange = await commet.subscriptions.previewChange({ id: "sub_xxx", planId: "pln_xxx", }); - lang: python label: Python source: |- from commet import Commet commet = Commet("ck_xxx") preview_change = commet.subscriptions.preview_change( "sub_xxx", plan_id="pln_xxx", ) - lang: go label: Go source: "client, err := commet.New(\"ck_xxx\")\nif err != nil {\n\tlog.Fatal(err)\n}\nctx := context.Background()\n\npreviewChange, err := client.Subscriptions.PreviewChange(ctx, \"sub_xxx\", &commet.PreviewChangePlanParams{\n\tPlanID: \"pln_xxx\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}" - lang: java label: Java source: |- import co.commet.Commet; import co.commet.params.PreviewChangePlanParams; var commet = Commet.builder().apiKey("ck_xxx").build(); var previewChange = commet.subscriptions().previewChange( "sub_xxx", PreviewChangePlanParams.builder("pln_xxx").build() ); - lang: php label: PHP source: |- use Commet\Commet; $commet = new Commet('ck_xxx'); $previewChange = $commet->subscriptions->previewChange( id: 'sub_xxx', planId: 'pln_xxx', ); components: headers: RequestId: description: >- Server-generated identifier that correlates this response with Platform logs. schema: type: string format: uuid schemas: PreviewChange: type: object properties: currency: type: string currentPlanCredit: type: integer minimum: -9007199254740991 maximum: 9007199254740991 newPlanCharge: type: integer minimum: -9007199254740991 maximum: 9007199254740991 estimatedTotal: type: integer minimum: -9007199254740991 maximum: 9007199254740991 effectiveDate: type: string format: date-time daysRemaining: type: integer minimum: -9007199254740991 maximum: 9007199254740991 totalDays: type: integer minimum: -9007199254740991 maximum: 9007199254740991 isUpgrade: type: boolean 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_preview livemode: type: boolean required: - currency - currentPlanCredit - newPlanCharge - estimatedTotal - effectiveDate - daysRemaining - totalDays - isUpgrade - 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 - [plan_change_scheduled](/docs/es/api-reference/errors/plan_change_scheduled.md) - [Change plan](/docs/es/api-reference/subscriptions/change-plan.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) - [free_plan_change_not_supported](/docs/es/api-reference/errors/free_plan_change_not_supported.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.