> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Switch the plan tier

> Switch the subscription into a target tier. The change takes effect immediately or at the end of the current period, depending on the target tier. Any proration credit or charge is collected into the next invoice.



## OpenAPI

````yaml post /api/customer/subscriptions/{id}/switch-plan-tier
openapi: 3.1.0
info:
  title: Fynn V2 Plans API
  version: 2026-06
  description: >-
    REST API for the Fynn V2 Plans. Use it to define plans with upgrade and
    downgrade tiers, sell them through checkout links, and let customers switch
    tiers from your customer portal. All amounts use the minor or decimal
    representation documented per field. Authenticate setup endpoints with an
    API token and customer endpoints with a customer token.
servers:
  - url: https://coreapi.io
    description: Production
  - url: https://preview.coreapi.io
    description: Sandbox
security:
  - ApiToken: []
tags:
  - name: Plans
    description: Create and manage plans, tiers and items.
  - name: Checkout Links
    description: Sell a plan tier through a hosted checkout link.
  - name: Plan switching (customer)
    description: Customer facing upgrade and downgrade between tiers.
paths:
  /api/customer/subscriptions/{id}/switch-plan-tier:
    post:
      tags:
        - Plan switching (customer)
      summary: Switch the plan tier
      description: >-
        Switch the subscription into a target tier. The change takes effect
        immediately or at the end of the current period, depending on the target
        tier. Any proration credit or charge is collected into the next invoice.
      operationId: switchPlanTier
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: 1280792f-4e23-793d-8e9c-3a1bf36630bd
          description: The subscription UUID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwitchPlanTierInput'
            example:
              planTierId: f5ece259-08ea-77a4-8bd9-9f3a9ed9e246
              items: []
      responses:
        '200':
          description: The switch result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwitchPlanTierResult'
        '401':
          description: Authentication is missing or the token is invalid.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemError'
        '403':
          description: The token is valid but lacks the required permission.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemError'
        '404':
          description: The requested resource does not exist for this Organisation.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemError'
        '422':
          description: The request failed validation or a business rule was violated.
          content:
            application/problem+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/ProblemError'
      security:
        - CustomerToken: []
components:
  schemas:
    SwitchPlanTierInput:
      type: object
      required:
        - planTierId
      properties:
        planTierId:
          type: string
          description: UUID of the target tier to switch into.
        items:
          type: array
          items:
            $ref: '#/components/schemas/PlanTierItemQuantityInput'
          default: []
          description: Optional quantity overrides for editable items of the target tier.
    SwitchPlanTierResult:
      type: object
      properties:
        subscriptionId:
          type: string
        newPlanTierId:
          type: string
        amendmentId:
          type: string
          description: Internal reference id of the resulting change.
        scheduleEventId:
          type: string
          description: Internal reference id of the resulting change.
        warnings:
          type: array
          items:
            type: string
          example:
            - active_discount_will_be_lost
    ProblemError:
      type: object
      description: >-
        Problem detail error body (application/problem+json). Additional members
        may be present depending on the error.
      properties:
        status:
          type: integer
          example: 404
        type:
          type: string
          description: Stable machine readable error key.
          example: PLAN__NOT_FOUND
        title:
          type: string
          example: An error occurred
        detail:
          type: string
          example: Plan not found.
      required:
        - status
        - type
        - title
        - detail
    ValidationError:
      type: object
      description: >-
        Validation error body (application/problem+json) returned when input
        fails field level validation.
      properties:
        status:
          type: integer
          example: 422
        type:
          type: string
          example: https://tools.ietf.org/html/rfc2616#section-10
        title:
          type: string
          example: Validation Failed
        violations:
          type: array
          items:
            type: object
            properties:
              propertyPath:
                type: string
                example: tiers[0].name
              message:
                type: string
                example: This value should not be blank.
              code:
                type: string
                nullable: true
      required:
        - status
        - type
        - title
        - violations
    PlanTierItemQuantityInput:
      type: object
      required:
        - planTierItemId
        - quantity
      properties:
        planTierItemId:
          type: string
          description: UUID of the tier item to override.
        quantity:
          type: number
          minimum: 0
          description: >-
            Requested quantity. Must lie within the item minQuantity and
            maxQuantity and the item must be quantity editable.
  securitySchemes:
    ApiToken:
      type: http
      scheme: bearer
      description: >-
        Organisation API token. Send it as Authorization: Bearer api_... The
        token is scoped to a single Organisation.
    CustomerToken:
      type: http
      scheme: bearer
      description: >-
        Customer access token. Send it as Authorization: Bearer <token>. Obtain
        it server side via POST /customers/{id}/authenticate (use the response
        accessToken), or from a customer portal session. The token must carry
        the customer:plan:switch permission.

````