---
title: "GET /v1/subscription/{handle}/upgrade"
method: GET
path: "/v1/subscription/{handle}/upgrade"
tags: ["subscription"]
---

# GET /v1/subscription/{handle}/upgrade

`GET /v1/subscription/{handle}/upgrade`

## Request

- Base URL: `https://customer-portal-api.frisbii.com`
- URL: `https://customer-portal-api.frisbii.com/v1/subscription/{handle}/upgrade`
- Auth: none declared

Get available subscription upgrade paths

## Path parameters

- `handle` string, required

## Response `200`

Successful operation

- SubscriptionUpgradePaths
  - `current_plan` Plan: Expanded target plan details (only when type is 'plan' and expand parameter includes 'plans')
    - `name` string, required: Name of the plan
    - `description` string: Description of the plan
    - `vat` number, float: Optional vat for this plan. Account default is used if none given.
    - `amount` integer, required: Amount for the plan in the smallest unit for the account currency
    - `quantity` integer: Optional default quantity of the subscription plan product for new subscriptions. Default is 1.
    - `prepaid` boolean: Subscriptions can either be prepaid where an amount is paid in advance, or the opposite. This setting only relates to handling of pause scenarios.
    - `handle` string, required: Per account unique handle for the subscription plan. Max length 255 with allowable characters [a-zA-Z0-9_.-@].
    - `version` integer, required: Plan version
    - `state` 'active' | 'superseded' | 'deleted', required: State of the subscription plan one of the following: `active`, `superseded`, `deleted`
    - `currency` string, required: Currency for the subscription plan in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) three letter alpha code
    - `created` string, date-time, required: Date when the subscription plan was created. In ISO-8601 extended offset date-time format.
    - `deleted` string, date-time: Date when the subscription plan was deleted. In ISO-8601 extended offset date-time format.
    - `dunning_plan` string: Dunning plan by handle to use for the subscription plan. Default dunning plan will be used if none given.
    - `tax_policy` string: Optional tax policy handle for this plan. If vat and tax policy is given, vat will be ignored.
    - `renewal_reminder_email_days` integer: Optional renewal reminder email settings. Number of days before next billing to send a reminder email.
    - `trial_reminder_email_days` integer: Optional end of trial reminder email settings. Number of days before end of trial to send a reminder email.
    - `partial_period_handling` 'bill_full' | 'bill_prorated' | 'bill_zero_amount' | 'no_bill': How to handle a potential initial partial billing period for fixed day scheduling. The options are to bill for a full period, bill prorated for the partial period, bill a zero amoumt, or not to consider the period before first fixed day a billing period. The default is to bill prorated. Options: `bill_full`, `bill_prorated`, `bill_zero_amount`, `no_bill`.
    - `include_zero_amount` boolean: Whether to add a zero amount order line to subscription invoices if plan amount is zero or the subscription overrides to zero amount. The default is to not include the line. If no other order lines are present the plan order line will be added.
    - `setup_fee` integer: Optional one-time setup fee billed with the first invoice or as a separate invoice depending on the setting `setup_fee_handling`.
    - `setup_fee_text` string: Optional invoice order text for the setup fee that
    - `setup_fee_handling` string: How the billing of the setup fee should be done. The options are: `first` - include setup fee as order line on the first scheduled invoice. `separate` - create a separate invoice for the setup fee, is appropriate if first invoice is not in conjunction with creation. `separate_conditional` - create a separate invoice for setup fee if the first invoice is not created in conjunction with the creation. Default is `first`.
    - `setup_fee_vat` number, float: Optional VAT for setup fee. Only returns the explicitly configured VAT rate, not the resolved rate from tax policy. Use effective_setup_fee_vat to see what will be used.
    - `setup_fee_tax_policy` string: Optional tax policy handle for setup fee. If both setup_fee_vat and setup_fee_tax_policy are configured, tax policy takes precedence.
    - `setup_fee_amount_incl_vat` boolean: Whether setup fee amount is including VAT. Only returns the explicitly configured value. Use effective_setup_fee_amount_incl_vat to see what will be used.
    - `partial_proration_days` boolean: For fixed day scheduling and prorated partial handling calculate prorated amount using whole days counting start day as a full day, or use by the minute proration calculation from start date time to the next period start. Default is true (whole days).
    - `fixed_trial_days` boolean: When using trial for fixed day scheduling use this setting to control if trial expires at midnight or the trial period is down to the minute. Default is true (trial until start of day). Trial in days can only be true if `partial_proration_days` is also set to true.
    - `minimum_prorated_amount` integer: When using prorated partial handling the prorated amount for plan and add-ons might result in very small amounts. A minimum prorated amount for plan and add-ons can be defined. If the prorated amount is below this minimum the amount will be changed to zero.
    - `account_funding` boolean: Indicates that Account Funding Transaction (AFT) is requested.
    - `cost_object` string: Cost object number (Kostenträger-Nr.) used for accounting export
    - `amount_incl_vat` boolean: Whether the amount is including VAT. Default true.
    - `fixed_count` integer: Fixed number of renewals for subscriptions using this plan. Equals the number of scheduled invoices. Default is no fixed amount of renewals.
    - `fixed_life_time_unit` 'months' | 'days': Time unit use for fixed life time
    - `fixed_life_time_length` integer: Optional fixed life time length for subscriptions using this plan. E.g. 12 months. Subscriptions will cancel after the fixed life time and expire when the active billing cycle ends.
    - `trial_interval_unit` 'months' | 'days': Time unit for free trial period
    - `trial_interval_length` integer: Optional free trial interval length. E.g. 1 monts.
    - `interval_length` integer: The length of intervals. E.g. every second month or every 14 days.
    - `schedule_type` 'manual' | 'daily' | 'weekly_fixedday' | 'month_startdate' | 'month_fixedday' | 'month_lastday', required: Scheduling type, one of the following: `manual`, `daily`, `weekly_fixedday`, `month_startdate`, `month_fixedday`, `month_lastday`. See documentation for descriptions of the different types.
    - `schedule_fixed_day` integer: If a fixed day scheduling type is used a fixed day must be provided. For months the allowed value is 1-28 for weeks it is 1-7
    - `schedule_fixed_hour` integer: Fixed hour (0-23) for monthly and weekly fixed day schedules. If not null, subscription will be scheduled at this hour.
    - `base_month` integer: For fixed month schedule types the base month can be used to control which months are eligible for start of first billing period. The eligible months are calculated as `base_month + k * interval_length` up to 12. E.g. to use quaterly billing in the months jan-apr-jul-oct, `base_month` 1 and `interval_length` 3 can be used. If not defined the first fixed day will be used as start of first billing period.
    - `notice_periods` integer: Optional number of notice periods for a cancel. The subscription will be cancelled for this number of full periods before expiring. Either from the cancellation date, or from the end of the the current period. See `notice_periods_after_current`. The default is to expire at the end of current period (0). A value of 1 (and `notice_periods_after_current` set to true) will for example result in a scenario where the subscription is cancelled until the end of current period, and then for the full subsequent period before expiring.
    - `notice_periods_after_current` boolean: If notice periods is set, this option controls whether the number of full notice periods should start at the end of the current period, or run from cancellation date and result in a partial period with partial amount for the last period. The default is true. E.g. if set to false and `notice_periods = 1` then the subscription will be cancelled for exactly for one period from the cancellation time and a partial amount will be billed at the start of the next billing period.
    - `fixation_periods` integer: Optional number of fixation periods. Fixation periods will guarantee that a subscription will have this number of paid full periods before expiring after a cancel. Default is to have no requirement (0).
    - `fixation_periods_full` boolean: If fixation periods are defined, and the subscription can have a partial prorated first period, this parameter controls if the the last period should be full, or partial to give exactly `fixation_periods` paid periods. Default is false.
    - `entitlements` string[]: List of entitlement handles to be added to the plan
    - `fixation_period_unit_type` 'day' | 'week' | 'month' | 'year': Time unit use in conjunction with fixation periods. If not fulfilled, it falls back to fixed_life_time_unit
    - `notice_period_unit_type` 'day' | 'week' | 'month' | 'year': Time unit used in conjunction with notice periods. If not fulfilled, it falls back to plan schedule_type
    - `contract_period` integer: Optional contract period length. E.g. 12 months.
    - `contract_period_unit_type` 'day' | 'week' | 'month' | 'year': Time unit used for the contract period
    - `contract_period_after_renewal_period` integer: Optional contract period length after renewal. E.g. 6 months.
    - `contract_period_after_renewal_unit_type` 'day' | 'week' | 'month' | 'year': Time unit used for the contract period after renewal
    - `subscription_duration_type` 'auto_renew' | 'fixed_number_of_billing_cycles' | 'end_on_contract_end': Subscription duration type
    - `effective_setup_fee_vat` number, float: Read-only. The effective VAT rate that will be used for setup fee after applying fallback logic. Returns the country-specific rate from setup_fee_tax_policy if set, otherwise returns setup_fee_vat if set, otherwise falls back to plan vat.
    - `effective_setup_fee_amount_incl_vat` boolean: Read-only. Whether the setup fee amount is including VAT after applying fallback logic. Returns setup_fee_amount_incl_vat if set, otherwise falls back to plan amount_incl_vat.
  - `configuration_handle` string: Upgradeable configuration handle
  - `configuration_name` string: Name of the configuration
  - `configuration_description` string: Description of the configuration
  - `available_upgrade_paths` AvailableUpgradePath[]: Available upgrade paths from the current plan
    - `target_plan` Plan: Expanded target plan details (only when type is 'plan' and expand parameter includes 'plans')
      - `name` string, required: Name of the plan
      - `description` string: Description of the plan
      - `vat` number, float: Optional vat for this plan. Account default is used if none given.
      - `amount` integer, required: Amount for the plan in the smallest unit for the account currency
      - `quantity` integer: Optional default quantity of the subscription plan product for new subscriptions. Default is 1.
      - `prepaid` boolean: Subscriptions can either be prepaid where an amount is paid in advance, or the opposite. This setting only relates to handling of pause scenarios.
      - `handle` string, required: Per account unique handle for the subscription plan. Max length 255 with allowable characters [a-zA-Z0-9_.-@].
      - `version` integer, required: Plan version
      - `state` 'active' | 'superseded' | 'deleted', required: State of the subscription plan one of the following: `active`, `superseded`, `deleted`
      - `currency` string, required: Currency for the subscription plan in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) three letter alpha code
      - `created` string, date-time, required: Date when the subscription plan was created. In ISO-8601 extended offset date-time format.
      - `deleted` string, date-time: Date when the subscription plan was deleted. In ISO-8601 extended offset date-time format.
      - `dunning_plan` string: Dunning plan by handle to use for the subscription plan. Default dunning plan will be used if none given.
      - `tax_policy` string: Optional tax policy handle for this plan. If vat and tax policy is given, vat will be ignored.
      - `renewal_reminder_email_days` integer: Optional renewal reminder email settings. Number of days before next billing to send a reminder email.
      - `trial_reminder_email_days` integer: Optional end of trial reminder email settings. Number of days before end of trial to send a reminder email.
      - `partial_period_handling` 'bill_full' | 'bill_prorated' | 'bill_zero_amount' | 'no_bill': How to handle a potential initial partial billing period for fixed day scheduling. The options are to bill for a full period, bill prorated for the partial period, bill a zero amoumt, or not to consider the period before first fixed day a billing period. The default is to bill prorated. Options: `bill_full`, `bill_prorated`, `bill_zero_amount`, `no_bill`.
      - `include_zero_amount` boolean: Whether to add a zero amount order line to subscription invoices if plan amount is zero or the subscription overrides to zero amount. The default is to not include the line. If no other order lines are present the plan order line will be added.
      - `setup_fee` integer: Optional one-time setup fee billed with the first invoice or as a separate invoice depending on the setting `setup_fee_handling`.
      - `setup_fee_text` string: Optional invoice order text for the setup fee that
      - `setup_fee_handling` string: How the billing of the setup fee should be done. The options are: `first` - include setup fee as order line on the first scheduled invoice. `separate` - create a separate invoice for the setup fee, is appropriate if first invoice is not in conjunction with creation. `separate_conditional` - create a separate invoice for setup fee if the first invoice is not created in conjunction with the creation. Default is `first`.
      - `setup_fee_vat` number, float: Optional VAT for setup fee. Only returns the explicitly configured VAT rate, not the resolved rate from tax policy. Use effective_setup_fee_vat to see what will be used.
      - `setup_fee_tax_policy` string: Optional tax policy handle for setup fee. If both setup_fee_vat and setup_fee_tax_policy are configured, tax policy takes precedence.
      - `setup_fee_amount_incl_vat` boolean: Whether setup fee amount is including VAT. Only returns the explicitly configured value. Use effective_setup_fee_amount_incl_vat to see what will be used.
      - `partial_proration_days` boolean: For fixed day scheduling and prorated partial handling calculate prorated amount using whole days counting start day as a full day, or use by the minute proration calculation from start date time to the next period start. Default is true (whole days).
      - `fixed_trial_days` boolean: When using trial for fixed day scheduling use this setting to control if trial expires at midnight or the trial period is down to the minute. Default is true (trial until start of day). Trial in days can only be true if `partial_proration_days` is also set to true.
      - `minimum_prorated_amount` integer: When using prorated partial handling the prorated amount for plan and add-ons might result in very small amounts. A minimum prorated amount for plan and add-ons can be defined. If the prorated amount is below this minimum the amount will be changed to zero.
      - `account_funding` boolean: Indicates that Account Funding Transaction (AFT) is requested.
      - `cost_object` string: Cost object number (Kostenträger-Nr.) used for accounting export
      - `amount_incl_vat` boolean: Whether the amount is including VAT. Default true.
      - `fixed_count` integer: Fixed number of renewals for subscriptions using this plan. Equals the number of scheduled invoices. Default is no fixed amount of renewals.
      - `fixed_life_time_unit` 'months' | 'days': Time unit use for fixed life time
      - `fixed_life_time_length` integer: Optional fixed life time length for subscriptions using this plan. E.g. 12 months. Subscriptions will cancel after the fixed life time and expire when the active billing cycle ends.
      - `trial_interval_unit` 'months' | 'days': Time unit for free trial period
      - `trial_interval_length` integer: Optional free trial interval length. E.g. 1 monts.
      - `interval_length` integer: The length of intervals. E.g. every second month or every 14 days.
      - `schedule_type` 'manual' | 'daily' | 'weekly_fixedday' | 'month_startdate' | 'month_fixedday' | 'month_lastday', required: Scheduling type, one of the following: `manual`, `daily`, `weekly_fixedday`, `month_startdate`, `month_fixedday`, `month_lastday`. See documentation for descriptions of the different types.
      - `schedule_fixed_day` integer: If a fixed day scheduling type is used a fixed day must be provided. For months the allowed value is 1-28 for weeks it is 1-7
      - `schedule_fixed_hour` integer: Fixed hour (0-23) for monthly and weekly fixed day schedules. If not null, subscription will be scheduled at this hour.
      - `base_month` integer: For fixed month schedule types the base month can be used to control which months are eligible for start of first billing period. The eligible months are calculated as `base_month + k * interval_length` up to 12. E.g. to use quaterly billing in the months jan-apr-jul-oct, `base_month` 1 and `interval_length` 3 can be used. If not defined the first fixed day will be used as start of first billing period.
      - `notice_periods` integer: Optional number of notice periods for a cancel. The subscription will be cancelled for this number of full periods before expiring. Either from the cancellation date, or from the end of the the current period. See `notice_periods_after_current`. The default is to expire at the end of current period (0). A value of 1 (and `notice_periods_after_current` set to true) will for example result in a scenario where the subscription is cancelled until the end of current period, and then for the full subsequent period before expiring.
      - `notice_periods_after_current` boolean: If notice periods is set, this option controls whether the number of full notice periods should start at the end of the current period, or run from cancellation date and result in a partial period with partial amount for the last period. The default is true. E.g. if set to false and `notice_periods = 1` then the subscription will be cancelled for exactly for one period from the cancellation time and a partial amount will be billed at the start of the next billing period.
      - `fixation_periods` integer: Optional number of fixation periods. Fixation periods will guarantee that a subscription will have this number of paid full periods before expiring after a cancel. Default is to have no requirement (0).
      - `fixation_periods_full` boolean: If fixation periods are defined, and the subscription can have a partial prorated first period, this parameter controls if the the last period should be full, or partial to give exactly `fixation_periods` paid periods. Default is false.
      - `entitlements` string[]: List of entitlement handles to be added to the plan
      - `fixation_period_unit_type` 'day' | 'week' | 'month' | 'year': Time unit use in conjunction with fixation periods. If not fulfilled, it falls back to fixed_life_time_unit
      - `notice_period_unit_type` 'day' | 'week' | 'month' | 'year': Time unit used in conjunction with notice periods. If not fulfilled, it falls back to plan schedule_type
      - `contract_period` integer: Optional contract period length. E.g. 12 months.
      - `contract_period_unit_type` 'day' | 'week' | 'month' | 'year': Time unit used for the contract period
      - `contract_period_after_renewal_period` integer: Optional contract period length after renewal. E.g. 6 months.
      - `contract_period_after_renewal_unit_type` 'day' | 'week' | 'month' | 'year': Time unit used for the contract period after renewal
      - `subscription_duration_type` 'auto_renew' | 'fixed_number_of_billing_cycles' | 'end_on_contract_end': Subscription duration type
      - `effective_setup_fee_vat` number, float: Read-only. The effective VAT rate that will be used for setup fee after applying fallback logic. Returns the country-specific rate from setup_fee_tax_policy if set, otherwise returns setup_fee_vat if set, otherwise falls back to plan vat.
      - `effective_setup_fee_amount_incl_vat` boolean: Read-only. Whether the setup fee amount is including VAT after applying fallback logic. Returns setup_fee_amount_incl_vat if set, otherwise falls back to plan amount_incl_vat.
    - `self_upgrade_allowed` boolean: Whether self-service upgrade is allowed

## Other responses

- `400`: Invalid request, see error codes at https://api.frisbii.com/v1/error_codes
- `401`: None or invalid credentials provided in access to secured resource
- `403`: Not authorized to perform resource operation
- `404`: Resource or referenced resource not found, see error codes at https://api.frisbii.com/v1/error_codes
- `429`: Request limiting exceeded, request rate or concurrent requests, see error code 122 and 123
- `500`: Internal service error, error is reported automatically to Frisbii

---

[API](https://skmtc.dev/frisbii/apis/frisbii-customer-portal-api.md) - [All operations](https://skmtc.dev/frisbii/apis/frisbii-customer-portal-api/llms.txt) - [OpenAPI document](https://skmtc.dev/frisbii/apis/frisbii-customer-portal-api/revisions/f0261fb63b1b?raw)