> ## 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. # Move subscribers to a plan version > Move a list of subscriptions, or every subscription of another version, to a newer version of the plan, at their next renewal or now. Nobody moves unless every one of them fits or has a change in changes; otherwise the response lists each one with what would make it fit. Subscriptions whose status does not allow a move, such as paused ones, and one-time subscriptions in a move at renewal are left out. A move keeps each subscription's currency, and a free version moves only to a free version and a paid one only to a paid version. Send preview to check without moving anyone. Move a list of subscriptions, or every subscription of another version, to a newer version of the plan, at their next renewal or now. Nobody moves unless every one of them fits or has a change in changes; otherwise the response lists each one with what would make it fit. Subscriptions whose status does not allow a move, such as paused ones, and one-time subscriptions in a move at renewal are left out. A move keeps each subscription's currency, and a free version moves only to a free version and a paid one only to a paid version. Send preview to check without moving anyone. The request returns `202` with the move. Follow it and each subscriber's status with [Get plan move](https://commet.co/docs/es/api-reference/plans/get-plan-move.md). `subscription.version_changed` fires for each subscription when its move takes effect. ## OpenAPI ````yaml /openapi/es/rest/2026-08-27.json post /plans/{id}/moves 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}/moves: post: tags: - Plans summary: Move subscribers to a plan version description: >- Move a list of subscriptions, or every subscription of another version, to a newer version of the plan, at their next renewal or now. Nobody moves unless every one of them fits or has a change in changes; otherwise the response lists each one with what would make it fit. Only active, trialing and past due subscriptions move. Paused ones, and listed subscriptions in another status or already on the destination, are left out. Send preview to check without moving anyone. operationId: create-plan-move 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: subscriptionIds: minItems: 1 maxItems: 10000 type: array items: type: string description: Public IDs of the subscriptions to move. toVersionId: type: string description: The version subscribers move to. effective: type: string enum: - now - period_end description: >- now changes features and the included amount today and the price at renewal; period_end moves each subscriber at its next renewal. changes: default: [] description: >- Per-subscriber changes that make each one fit, applied at its renewal. type: array items: type: object properties: subscriptionId: type: string keepOnVersion: description: Leave this subscriber on its version. type: boolean const: true billingInterval: type: string enum: - weekly - monthly - quarterly - semiannual - yearly seatLimit: description: Lower its seats to the version's limit at renewal. type: boolean const: true removeAddonIds: description: Add-ons it stops paying at renewal. type: array items: type: string required: - subscriptionId preview: default: false description: Check every subscriber without moving anyone. type: boolean required: - subscriptionIds - toVersionId - effective additionalProperties: false - type: object properties: fromVersionId: type: string description: >- Move every active, trialing and past due subscription on this version of the plan. toVersionId: type: string description: The version subscribers move to. effective: type: string enum: - now - period_end description: >- now changes features and the included amount today and the price at renewal; period_end moves each subscriber at its next renewal. changes: default: [] description: >- Per-subscriber changes that make each one fit, applied at its renewal. type: array items: type: object properties: subscriptionId: type: string keepOnVersion: description: Leave this subscriber on its version. type: boolean const: true billingInterval: type: string enum: - weekly - monthly - quarterly - semiannual - yearly seatLimit: description: Lower its seats to the version's limit at renewal. type: boolean const: true removeAddonIds: description: Add-ons it stops paying at renewal. type: array items: type: string required: - subscriptionId preview: default: false description: Check every subscriber without moving anyone. type: boolean required: - fromVersionId - toVersionId - effective additionalProperties: false responses: '202': 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/PlanMove' example: id: pvm_1a2b3c4d toVersionId: plr_9i0j1k2l fromVersionIds: - plr_1a2b3c4d effective: period_end preview: false status: moving counts: moving: 179 moved: 0 needsAChange: 1 leftOut: 3 canceled: 0 keptOnVersion: 0 subscriptions: - subscriptionId: sub_1a2b3c4d status: moving code: null message: null - subscriptionId: sub_9i0j1k2l status: needs_a_change code: addon_unavailable message: >- The version does not sell the add-on SSO, which the subscription has active. Deactivate it before moving the subscription. - subscriptionId: sub_5e6f7g8h status: left_out code: invalid_subscription_status message: >- A paused subscription cannot change versions. Only active, trialing and past due subscriptions can. createdAt: '2026-09-07T12:00:00.000Z' completedAt: null canceledAt: null object: plan_move '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: PlanMove: type: object properties: id: description: Public move ID. Null for a preview, which records nothing. type: - string - 'null' toVersionId: type: string fromVersionIds: type: array items: type: string description: The versions its subscribers are moving from. effective: type: string enum: - now - period_end preview: type: boolean status: type: string enum: - checking - blocked - checked - moving - completed - canceled description: >- checked is a preview where everyone fits; moving while subscribers wait for their move; completed once every move ran; canceled after it was canceled. counts: type: object properties: moving: type: integer minimum: -9007199254740991 maximum: 9007199254740991 moved: type: integer minimum: -9007199254740991 maximum: 9007199254740991 needsAChange: type: integer minimum: -9007199254740991 maximum: 9007199254740991 leftOut: type: integer minimum: -9007199254740991 maximum: 9007199254740991 canceled: type: integer minimum: -9007199254740991 maximum: 9007199254740991 keptOnVersion: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - moving - moved - needsAChange - leftOut - canceled - keptOnVersion additionalProperties: false subscriptions: type: array items: type: object properties: subscriptionId: type: string status: type: string enum: - moving - moved - needs_a_change - left_out - canceled - kept_on_version description: >- moving waits for its renewal or is being moved; moved is on the destination; needs_a_change could not move and keeps its version until it is resolved or kept; left_out was not moved because it was not active, trialing or past due, such as a paused subscription (invalid_subscription_status), or because a listed subscription was already on the destination (no_change_requested); canceled was canceled before it moved; kept_on_version was left on its version by the merchant. code: type: - string - 'null' message: type: - string - 'null' required: - subscriptionId - status - code - message additionalProperties: false createdAt: anyOf: - type: string format: date-time - type: 'null' completedAt: anyOf: - type: string format: date-time - type: 'null' canceledAt: anyOf: - type: string format: date-time - type: 'null' object: type: string const: plan_move livemode: type: boolean required: - id - toVersionId - fromVersionIds - effective - preview - status - counts - subscriptions - createdAt - completedAt - canceledAt - 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.