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

# Preview subscription plan change

> Use when showing a customer the cost of a plan change before they confirm (e.g. upgrade/downgrade preview with proration).



## OpenAPI

````yaml /api-reference/openapi.json post /subscriptions/{id}/change/preview
openapi: 3.0.1
info:
  title: Flexprice API
  description: Flexprice API Service
  contact:
    name: API Support
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
  version: '1.0'
servers:
  - url: https://us.api.flexprice.io/v1
    description: US Region
  - url: https://api.cloud.flexprice.io/v1
    description: India Region
security: []
paths:
  /subscriptions/{id}/change/preview:
    post:
      tags:
        - Subscriptions
      summary: Preview subscription plan change
      description: >-
        Use when showing a customer the cost of a plan change before they
        confirm (e.g. upgrade/downgrade preview with proration).
      operationId: previewSubscriptionChange
      parameters:
        - name: id
          in: path
          description: Subscription ID
          required: true
          schema:
            type: string
      requestBody:
        description: Subscription change preview request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionChangeRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionChangePreviewResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    SubscriptionChangeRequest:
      required:
        - billing_cadence
        - billing_cycle
        - billing_period
        - proration_behavior
        - target_plan_id
      type: object
      properties:
        billing_cadence:
          $ref: '#/components/schemas/types.BillingCadence'
        billing_cycle:
          $ref: '#/components/schemas/types.BillingCycle'
        billing_period:
          $ref: '#/components/schemas/types.BillingPeriod'
        billing_period_count:
          type: integer
          description: >-
            billing_period_count is the billing period count for the new
            subscription
        change_at:
          $ref: '#/components/schemas/types.ScheduleType'
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            metadata contains additional key-value pairs for storing extra
            information
        proration_behavior:
          $ref: '#/components/schemas/types.ProrationBehavior'
        target_plan_id:
          type: string
          description: target_plan_id is the ID of the new plan to change to (required)
      description: Request object for changing a subscription plan (upgrade/downgrade)
    SubscriptionChangePreviewResponse:
      type: object
      properties:
        change_type:
          $ref: '#/components/schemas/types.SubscriptionChangeType'
        current_plan:
          $ref: '#/components/schemas/PlanSummary'
        effective_date:
          type: string
          description: effective_date is when the change would take effect
          format: date-time
        metadata:
          type: object
          additionalProperties:
            type: string
          description: metadata from the request
        new_billing_cycle:
          $ref: '#/components/schemas/BillingCycleInfo'
        next_invoice_preview:
          $ref: '#/components/schemas/InvoicePreview'
        proration_details:
          $ref: '#/components/schemas/ProrationDetails'
        subscription_id:
          type: string
          description: subscription_id is the ID of the subscription being changed
        target_plan:
          $ref: '#/components/schemas/PlanSummary'
        warnings:
          type: array
          description: warnings contains any warnings about the change
          items:
            type: string
      description: Response showing the financial impact of a subscription plan change
    errors.ErrorResponse:
      type: object
      properties:
        code:
          type: string
          enum:
            - not_found
            - already_exists
            - version_conflict
            - validation_error
            - invalid_operation
            - permission_denied
            - http_client_error
            - database_error
            - system_error
            - internal_error
            - service_unavailable
        details:
          type: object
          additionalProperties:
            type: object
        http_status_code:
          type: integer
        message:
          type: string
      x-speakeasy-name-override: ErrorResponse
    types.BillingCadence:
      type: string
      enum:
        - RECURRING
      x-enum-varnames:
        - BILLING_CADENCE_RECURRING
      x-speakeasy-name-override: BillingCadence
    types.BillingCycle:
      type: string
      enum:
        - anniversary
        - calendar
      x-enum-varnames:
        - BillingCycleAnniversary
        - BillingCycleCalendar
      x-speakeasy-name-override: BillingCycle
    types.BillingPeriod:
      type: string
      enum:
        - MONTHLY
        - ANNUAL
        - WEEKLY
        - DAILY
        - QUARTERLY
        - HALF_YEARLY
        - ONETIME
      x-enum-varnames:
        - BILLING_PERIOD_MONTHLY
        - BILLING_PERIOD_ANNUAL
        - BILLING_PERIOD_WEEKLY
        - BILLING_PERIOD_DAILY
        - BILLING_PERIOD_QUARTER
        - BILLING_PERIOD_HALF_YEAR
        - BILLING_PERIOD_ONETIME
      x-speakeasy-name-override: BillingPeriod
    types.ScheduleType:
      type: string
      enum:
        - immediate
        - end_of_period
      x-enum-varnames:
        - ScheduleTypeImmediate
        - ScheduleTypePeriodEnd
      x-speakeasy-name-override: ScheduleType
    types.ProrationBehavior:
      type: string
      enum:
        - create_prorations
        - none
      x-enum-comments:
        ProrationBehaviorCreateProrations: 'Default: Create credits/charges on invoice'
        ProrationBehaviorNone: Calculate but don't apply (e.g., for previews)
      x-enum-varnames:
        - ProrationBehaviorCreateProrations
        - ProrationBehaviorNone
      x-speakeasy-name-override: ProrationBehavior
    types.SubscriptionChangeType:
      type: string
      enum:
        - upgrade
        - downgrade
        - lateral
      x-enum-varnames:
        - SubscriptionChangeTypeUpgrade
        - SubscriptionChangeTypeDowngrade
        - SubscriptionChangeTypeLateral
      x-speakeasy-name-override: SubscriptionChangeType
    PlanSummary:
      type: object
      properties:
        description:
          type: string
          description: description of the plan
        id:
          type: string
          description: id of the plan
        lookup_key:
          type: string
          description: lookup_key of the plan
        name:
          type: string
          description: name of the plan
    BillingCycleInfo:
      type: object
      properties:
        billing_anchor:
          type: string
          description: billing_anchor is the new billing anchor
          format: date-time
        billing_cadence:
          $ref: '#/components/schemas/types.BillingCadence'
        billing_period:
          $ref: '#/components/schemas/types.BillingPeriod'
        billing_period_count:
          type: integer
          description: billing_period_count is the billing period count
        period_end:
          type: string
          description: period_end is the end of the new billing period
          format: date-time
        period_start:
          type: string
          description: period_start is the start of the new billing period
          format: date-time
    InvoicePreview:
      type: object
      properties:
        currency:
          type: string
          description: currency is the currency for all amounts
        due_date:
          type: string
          description: due_date is when the invoice would be due
          format: date-time
        line_items:
          type: array
          description: line_items contains preview of line items
          items:
            $ref: '#/components/schemas/InvoiceLineItemPreview'
        subtotal:
          type: string
          description: subtotal is the subtotal amount before taxes
        tax_amount:
          type: string
          description: tax_amount is the total tax amount
        total:
          type: string
          description: total is the total amount including taxes
    ProrationDetails:
      type: object
      properties:
        charge_amount:
          type: string
          description: charge_amount is the charge amount for the new subscription
        charge_description:
          type: string
          description: charge_description describes what the charge is for
        credit_amount:
          type: string
          description: credit_amount is the credit amount from the old subscription
        credit_description:
          type: string
          description: credit_description describes what the credit is for
        currency:
          type: string
          description: currency is the currency for all amounts
        current_period_end:
          type: string
          description: current_period_end is the end of the current billing period
          format: date-time
        current_period_start:
          type: string
          description: current_period_start is the start of the current billing period
          format: date-time
        days_remaining:
          type: integer
          description: days_remaining is the number of days remaining in the current period
        days_used:
          type: integer
          description: days_used is the number of days used in the current period
        net_amount:
          type: string
          description: net_amount is the net amount (charge - credit)
        proration_date:
          type: string
          description: proration_date is the date used for proration calculations
          format: date-time
    InvoiceLineItemPreview:
      type: object
      properties:
        amount:
          type: string
          description: amount for this line item
        description:
          type: string
          description: description of the line item
        is_proration:
          type: boolean
          description: is_proration indicates if this line item is a proration
        period_end:
          type: string
          description: period_end for this line item (if applicable)
          format: date-time
        period_start:
          type: string
          description: period_start for this line item (if applicable)
          format: date-time
        quantity:
          type: string
          description: quantity for this line item
        unit_price:
          type: string
          description: unit_price for this line item
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Enter your API key in the format *x-api-key <api-key>**
      name: x-api-key
      in: header

````