> ## 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. 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.

> [!NOTE]
>
> This reference describes API version `2026-05-01`. Send `Commet-Version: 2026-05-01` with your request.


## OpenAPI

````yaml /openapi/en/rest/2026-05-01.json post /plans/{id}/moves
openapi: 3.1.0
info:
  title: Commet API
  version: '2026-05-01'
  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: 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: 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-05-01'
          example: '2026-05-01'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - 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
                        additionalProperties: false
                    preview:
                      default: false
                      description: Check every subscriber without moving anyone.
                      type: boolean
                  required:
                    - subscriptionIds
                    - toVersionId
                    - effective
                    - changes
                    - preview
                  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
                        additionalProperties: false
                    preview:
                      default: false
                      description: Check every subscriber without moving anyone.
                      type: boolean
                  required:
                    - fromVersionId
                    - toVersionId
                    - effective
                    - changes
                    - preview
                  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:
                type: object
                properties:
                  success:
                    const: true
                  data:
                    $ref: '#/components/schemas/PlanMove'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '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'
        '500':
          description: Internal server error
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
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'
      required:
        - id
        - toVersionId
        - fromVersionIds
        - effective
        - preview
        - status
        - counts
        - subscriptions
        - createdAt
        - completedAt
        - canceledAt
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        success:
          const: false
        code:
          type: string
        message:
          type: string
        details: {}
      required:
        - success
        - code
        - message
  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.