All Products
Search

This Product

    Elastic Compute Service:ModifyPrepayInstanceSpec

    Document Center

    Elastic Compute Service:ModifyPrepayInstanceSpec

    Last Updated:Jun 29, 2026

    Modifies the instance type of a subscription ECS instance. You can upgrade or downgrade the instance type. The new instance type takes effect for the entire lifecycle of the instance.

    Operation description

    Before you call this operation, make sure that you fully understand the billing methods, pricing, and downgrade refund rules of ECS.

    This operation is asynchronous. The configuration change takes effect after approximately 5 to 10 seconds. Before you upgrade or downgrade ECS instance type of a subscription ECS instance, you can call DescribeResourcesModification to query ECS instance types to which the current instance can be changed.

    Precautions

    • If the NVMe property of the source and target instance types are different (the NvmeSupport field returned by DescribeInstanceTypes) and the operating system is Windows (the OSType field returned by DescribeInstances), complete the preventive measures before you perform the Upgrade/Downgrade.

    • Expired instances cannot be changed to a different instance type. Complete the renewal and try again.

    • Downgrade the instance type:

      • The instance must be in the Stopped (Stopped) state.

      • The price difference between the original and new instance types is refunded to your original billing method. Used vouchers are not refundable. The payer receives the refund.

      • The new instance type takes effect only after you start the instance after the Upgrade/Downgrade.

    • Upgrade the instance type:

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    ecs:ModifyPrepayInstanceSpec

    update

    *Instance

    acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    InstanceId

    string

    Yes

    The instance ID.

    i-bp67acfmxazb4ph****
    RegionId

    string

    Yes

    The region ID of the instance. You can call DescribeRegions to query the most recent region list.

    cn-hangzhou
    InstanceType

    string

    Yes

    The target instance type for the Upgrade/Downgrade. For more information, see Instance family or invoke DescribeInstanceTypes.

    ecs.g5.xlarge
    OperatorType

    string

    No

    The type of the operation. Valid values:

    Note

    This parameter is optional. The system can automatically determine whether the operation is an upgrade or a downgrade. If you upload this parameter, follow the rules below.

    • upgrade: upgrades the instance type. Make sure that your account payment method has a sufficient balance.

    • downgrade: decrease the quota of the instance type. When the instance type specified by InstanceType is lower than the current instance type, set OperatorType to downgrade.

    Note

    For precautions about upgrading or downgrading instance types, see the operation description section above.

    upgrade
    ClientToken

    string

    No

    The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but make sure that the token is unique among different requests. The ClientToken value can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.

    123e4567-e89b-12d3-a456-426655440000
    AutoPay

    boolean

    No

    Specifies whether to automatically complete the payment when you upgrade the instance type. Valid values:

    • true: The payment is automatically completed.

    • false: Only an order is created. No payment is made.

    Default value: true.

    Note

    • If automatic payment is enabled, make sure that your payment method has a sufficient balance. Otherwise, an abnormal order is generated, and you can only cancel the order.

    • If your payment method balance is insufficient, you can set AutoPay to false to generate an unpaid order. Then, you can logon to the ECS console to pay for the order.

    • When OperatorType is set to downgrade, the AutoPay parameter is ignored.

    true
    MigrateAcrossZone

    boolean

    No

    Specifies whether to support cross-cluster instance type changes. Valid values:

    • true: supported.

    • false: not supported.

    Default value: false.

    When the MigrateAcrossZone parameter is set to true, take note of the following items after you perform the optimization on the Elastic Compute Service instance based on the response:

    VPC-type instances: For retired instance types, when a non-I/O optimized instance is changed to an I/O optimized instance, the disk device names and software authorization codes of the server change. For Linux instances, basic disks (cloud) are identified as xvda or xvdb. Ultra disks (cloud_efficiency) and standard SSDs (cloud_ssd) are identified as vda or vdb.

    false
    SystemDisk.Category

    string

    No

    The new system disk category. Valid values:

    • cloud_efficiency: ultra disk.

    • cloud_ssd: standard SSD.

    Note

    This parameter is valid only when you perform an Increase Quota from a retired instance type to a Normal instance family and change a non-I/O optimization instance to an I/O optimization instance.

    cloud_efficiency
    RebootTime

    string

    No

    The restart time of the instance. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time must be in UTC.

    2018-01-01T12:05Z
    EndTime

    string

    No

    The end time of the temporary instance type change. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time must be in UTC.

    2018-01-01T12:05Z
    RebootWhenFinished

    boolean

    No

    Specifies whether to immediately restart the instance after the instance type change is complete. Valid values:

    • true: The instance is immediately restarted.

    • false: The instance is not restarted.

    Default value: false.

    Note

    If the instance is in the Stopped state, the instance remains stopped even if you set RebootWhenFinished to true. No operation is performed.

    false
    ModifyMode

    string

    No

    Note

    This parameter is not publicly available.

    null
    Disk

    array<object>

    No

    Note

    This parameter is not publicly available.

    object

    No

    Note

    This parameter is not publicly available.

    DiskId

    string

    No

    Note

    This parameter is not publicly available.

    null
    Category

    string

    No

    Note

    This parameter is not publicly available.

    null
    PerformanceLevel

    string

    No

    Note

    This parameter is not publicly available.

    null

    Response elements

    Element

    Type

    Description

    Example

    object

    OrderId

    string

    The order ID.

    1234567890
    RequestId

    string

    The request ID.

    473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

    Examples

    Success response

    JSON format

    {
  "OrderId": "1234567890",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 InvalidInstanceType.ValueUnauthorized The specified InstanceType is not authorized.
    400 InvalidInstanceType.ValueNotSupported The specified InstanceType does not exist or beyond the permitted range. The specified instance type does not exist or you are not authorized to manage instances of this instance type.
    400 InvalidBillingMethod.ValueNotSupported The operation is not permitted due to an invalid billing method of the instance. The operation is not supported due to the invalid instance billing method.
    400 InvalidInstance.PurchaseNotFound The specified instance has no purchase history. The order record for the instance does not exist.
    400 InvalidInstance.UnpaidOrder The specified instance has unpaid order. The specified instance still has unpaid orders.
    400 InvalidInstanceType.NotSupported The specified InstanceType is not Supported.
    400 OrderCreationFailed Order creation failed, please check your params and try it again later.
    400 Throttling You have made too many requests within a short time; your request is denied due to request throttling.
    400 Account.Arrearage Your account has an outstanding payment. Your account has overdue payments.
    400 InvalidInstanceId.NotFound The specified InstanceId does not exist.
    400 InvalidRebootTime.MalFormed The specified rebootTime is not valid. The specified RebootTime parameter is invalid.
    400 InvalidRebootTime.ValueNotSupported The specified RebootTime is not valid. The specified RebootTime is invalid.
    400 IdempotenceParamNotMatch Request uses a client token in a previous request but is not identical to that request. This request and the previous request contain the same client token but different other parameters.
    400 InvalidInstanceChargeType.ValueNotSupported %s The specified InstanceChargeType parameter is invalid.
    400 InvalidStatus.NotStopped Instance status must be stopped.
    400 InvalidAction %s The operation is invalid.
    400 InstanceDowngrade.QuotaExceed Quota of instance downgrade is exceed. The maximum number of configuration downgrades allowed for the instance has been reached.
    400 InvalidParameter %s The specified parameter is invalid.
    400 OperationDenied The current user does not support this operation. Your account does not support this operation.
    400 LastOrderProcessing The previous order is still processing, please try again later. The order is being processed. Try again later.
    400 InvalidOperation.VpcHasEnabledAdvancedNetworkFeature The specified vpc has enabled advanced network feature. Advanced features are enabled for the specified VPC. You cannot create low-specification instances in the VPC.
    400 InvalidAction.WithActiveElasticUpgrade The instance has active Elastic Upgrade.
    400 InstanceTypeNotSupported.TooManyDisksAttached %s
    400 QuotaExceed.DiskCapacity The used capacity of disk type has exceeded the quota in the zone, %s. The capacity of disks that belong to the specified disk category exceeds the quota limit for the zone.
    400 MissingParameter.DiskCategory The specified parameter Disk.Category can not be null when Disk.DiskId is specified.
    400 InvalidParameter.DiskCategory The specified parameter Disk.Category is not valid.
    400 InvalidPerformanceLevel.Malformed The specified parameter Disk.n.PerformanceLevel is not valid.
    400 InvalidSystemDiskCategory.NotMatchInstanceType The system disk category does not match the instance type.
    400 QuotaExceed.RufundVcpu The maximum number of refunded vcpu is exceeded: %s . The maximum number of refund vCPUs is exceeded. For more information about the amount, see the return value of the %s placeholder in the error message.
    400 NoPermission.Price The operation requires price permission. Please either apply for permission from your main account, or set the parameter AutoPay as true. This operation requires price permission. Please apply for permission to your master account, or set the parameter AutoPay to true for automatic payment.
    400 NoPermission.Refund The operation requires refund permission. Please apply for permission from your main account. This account does not have permission to operate refund, and the main account needs to authorize refund-related permissions.
    400 InvalidInstanceStatus The current status of the instance does not support this operation.
    400 InvalidOperation.InstanceRenewWithDowngradeInPlan The operation is denied due to the specified instance has renew with downgrade record in plan. There are renewal downgrade orders that have not yet taken effect. This operation is not allowed before the order takes effect.
    400 InvalidOperation.OnlineModificationUnsupported Online modification of instance type is not supported for the specified instance due to its CPU topology.
    400 InvalidInstanceType.NotSupportCpuOptionsNestedVirtualization The specified instance type does not support CpuOptions.NestedVirtualization: %s. The specified instance type does not support CpuOptions.NestedVirtualization value.
    401 InvalidInstanceType.ValueUnauthorized The specified InstanceType is not authorized. You are not authorized to use the specified instance type.
    500 InternalError The request processing has failed due to some unknown error, exception or failure. An internal error has occurred. Try again later.
    500 ImageOrderFailed Create marketplace image order failed. Failed to create the Alibaba Cloud Marketplace order. Submit a ticket.
    403 OperationDenied.NoStock The specified instance is out of usage. The resources of the specified instance type are insufficient.
    403 InvalidInstanceType.ValueNotSupported The specified InstanceType does not exist or beyond the permitted range.
    403 InvalidUser.PassRoleForbidden The RAM user does not have privilege to pass a role. RAM users are not authorized to assign RAM roles.
    403 ImageNotSupportInstanceType The specified image does not support the specified InstanceType. The specified image does not support the specified instance type.
    403 InstanceType.Offline %s The operation is not supported while the instance type is retired or while resources of the instance type are insufficient.
    403 IncorrectInstanceStatus The current status of the resource does not support this operation.
    403 Throttling You have made too many requests within a short time; your request is denied due to request throttling.
    403 InvalidParameter.InstanceId %s The specified InstanceId parameter is invalid.
    403 OperationDenied %s
    403 InvalidInstanceStatus The current status of the instance does not support this operation. The instance is in a state that does not support the current operation.
    403 InvalidOperation.StarterPackage StarterPackage not support modification.
    403 InvalidInstance.PreInstanceExpired Instance business status is not Expired.
    403 InvalidInstance.EipNotSupport The special instance with eip not support operate, please unassociate eip first. The operation is not supported while an EIP is associated with the instance. Disassociate the EIP first.
    403 OperationDenied.ImageNotValid The specified image is not authorized.
    403 OperationDenied.LocalDiskUnsupported The configuration change is not allowed when the specified instance has local disks mounted. Instance types cannot be changed for instances that have local disks attached.
    403 InvalidOperation.EniCountExceeded %s
    403 InvalidOperation.Ipv4CountExceeded %s The operation is valid because the maximum number of IPv4 addresses has been reached.
    403 InvalidOperation.Ipv6CountExceeded %s The operation is valid because the maximum number of IPv6 addresses has been reached.
    403 InvalidOperation.Ipv6NotSupport %s
    403 InvalidOperation.Ipv4NotSupport %s
    403 InvalidInstance.NotFoundSystemDisk The specified instance has no system disk.
    403 InvalidInstanceType.NotSupportDiskCategory The instanceType of the specified instance does not support this disk category. The instance type does not support the current disk category. Try another instance type. For information about the disk categories supported by instance types, see the instance family documentation.
    403 QuotaExceed.ElasticQuota No additional quota is available for the specified ECS instance type. The maximum number of instances of the specified instance type in the region has been reached. Reduce the quantity of instances that you want to purchase or try another region or instance type. Alternatively, you can go to the ECS console or Quota Center to request a quota increase.
    403 InvalidResourceType.NotSupported %s The specified resource combination does not exist. Change to another zone or specification.
    403 InvalidOperation.MaxEniQueueNumberExceeded %s
    403 InvalidOperation.ExceedInstanceTypeQueueNumber %s The maximum number of queues for all ENIs on an instance has been exceeded. For more information, see the return value of the %s placeholder in the error message.
    403 InvalidParameter.InvalidEniQueueNumber %s
    403 HibernationConfigured.InstanceOperationForbidden The operation is not permitted due to limit of the hibernation configured instance. The operation cannot be performed due to the limitations of instances for which the instance hibernation feature is enabled.
    403 InvalidOperation.MaxModifyOnlineNumberExceeded The specified instance has reached the maximum number of modify online attempts and needs to be rebooted.
    403 InvalidOperation.RebootingRequired The specified instance needs to be rebooted.
    403 InvalidOperation.OSTypeNotSupported The specified OS type is not supported.
    403 OperationDenied.UnpaidOrder The specified instance has unpaid order. Your account has unpaid orders for the specified instance. You can log on to the ECS console to pay for the orders.
    403 InvalidDisk.DetachedSystemDisk The specified resource is/has a detached system disk %s , not support current operation.
    403 InvalidDataDiskCategory.ValueNotSupported The specified Category of Data Disk is not valid. The specified data disk type is not supported.
    403 InvalidDiskCategory.NotSupported The upgrade operation of instance does not support this category of disk.
    404 InvalidRegionId.NotFound The specified RegionId does not exist. The specified region ID does not exist.
    404 BillingMethodNotFound The account has not chosen any billing method. No billing method is selected for the Alibaba Cloud account.
    404 InvalidInstanceId.NotFound The specified InstanceId does not exist. The specified instanceId is invalid.
    503 LimitedOperation.ServiceUnavailable The service is currently unavailable. Please try again later. The service is currently unavailable. Please try again later.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.