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

Description

Before you call this operation, make sure that you have fully understood the billing methods and pricing schedule of ECS.

Before changing the subscription instance type, you can call the DescribeResourcesModification operation to query the instance types you can change to. For more information, see the Python SDK example in Query available resources for ECS configuration change.

When you call this operation, take note of the following items:

  • You cannot modify the instance type of an expired instance. You can renew the instance and try again.
  • When you downgrade an instance type, take note of the following items:
    • The instance must be in the Stopped state.
    • You must specify the operation type by setting OperatorType=downgrade.
    • You can downgrade an instance a maximum of three times. That is, the refund for the price difference cannot exceed three times. Downgrade operations include instance type downgrades, bandwidth downgrades, and the change of the disk billing method from subscription to pay-as-you-go.
    • The price difference is refunded to the payment account you used. Price difference of coupon purchases are not refunded.
  • This operation is asynchronous and you need to wait for about five to ten seconds for the instance type change to complete. Then, you must call the RebootInstance operation or restart the instance in the console to allow the instance type change to take effect. Restarting the operating system does not allow the instance type change to take effect.
    • If the instance is in the Stopped state, you only need to start the instance and do not need to restart the operating system.
    • If RebootWhenFinished=true is set for the instance, you do not need to restart the operating system.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String No ModifyPrepayInstanceSpec

The operation that you want to perform. Set the value to ModifyPrepayInstanceSpec.

InstanceId String Yes i-bp67acfmxazb4ph***

The ID of the instance.

InstanceType String Yes ecs.g5.xlarge

The new instance type. For information about the new instance type, see Instance families or call the DescribeInstanceTypes operation.

RegionId String Yes cn-hangzhou

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

OperatorType String No upgrade

The operation type. Default value: upgrade. Valid values:

  • upgrade: upgrades the instance type. Make sure that the balance in your payment account is sufficient.
  • downgrade: downgrades the instance type. When the instance type specified by InstanceType is inferior to the current instance type, you must set OperatorType=downgrade.
Note For more information about the precautions on upgrading or downgrading instance types, see the preceding "Description" section in this topic.
ClientToken String No 123e4567-e89b-12d3-a456-426655440000

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

AutoPay Boolean No true

Specifies whether to enable automatic payment when you upgrade the instance type. Default value: true. Valid values:

  • true: Automatic payment is enabled.
    Note When your account balance is insufficient, your order will become invalid and you have to cancel this order. If your account balance is insufficient, to prevent your order from becoming invalid, you can set AutoPay to false. This ensures a normal order is generated. Then you can log on to the ECS console to pay for the order.
  • false: No payment is made and only an order is generated.

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

MigrateAcrossZone Boolean No false

Specifies whether to enable cross-cluster instance type upgrade.

Default value: false.

When the MigrateAcrossZone parameter is set to true and you upgrade the ECS instance based on the returned information, take note of the following items:

Classic network-type instances:

  • For Phased-out instance types, when a non-I/O optimized instance is upgraded to an I/O optimized instance, the following items are modified: private IP address, disk device name, and software authorization code. 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.
  • For Instance families available on the Alibaba Cloud market, the private IP address is modified after the instance type is upgraded.

VPC-type instances: For phased-out instance types, when a non-I/O optimized instance is upgraded to an I/O optimized instance, the following items are modified: disk device name and software authorization code. 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.

SystemDisk.Category String No cloud_efficiency

The category of the target system disk. This parameter is valid only when you upgrade one of the Phased-out instance types to one instance type of the Instance families available on the Alibaba Cloud market and upgrade a non-I/O optimized instance to an I/O optimized instance. Valid values:

  • cloud_efficiency: ultra disks
  • cloud_ssd: standard SSDs
RebootTime String No 2018-01-01T12:05:00Z

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

EndTime String No 2018-01-01T12:05:00Z

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

RebootWhenFinished Boolean No false

Specifies whether to restart the instance immediately after the change of instance type is completed.

Default value: false.

Note If the instance is in the Stopping state, even if you set RebootWhenFinished=true, the original state remains unchanged and no operation is performed.

Response parameters

Parameter Type Example Description
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

OrderId String 1111111111111111111111110

The ID of the generated order.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=ModifyPrepayInstanceSpec
&RegionId=cn-hangzhou
&InstanceId=i-bp67acfmxazb4ph***
&InstanceType=ecs.g5.xlarge
&AutoPay=true
&OperatorType=upgrade
&ClientToken=123e4567-e89b-12d3-a456-426655440000
&<Common request parameters>

Sample success responses

XML format

<ModifyPrepayInstanceSpecResponse>
      <RequestId>04F0F334-1335-436C-A1D7-6C044FE73368</RequestId>
      <OrderId>1011111111111111</OrderId>
</ModifyPrepayInstanceSpecResponse>

JSON format

{
    "RequestId": "04F0F334-1335-436C-A1D7-6C044FE73368",
    "OrderId": 1011111111111111
}

Error codes

HTTP status code Error code Error message Description
404 InvalidRegionId.NotFound The specified RegionId does not exist. The error message returned because the specified region ID does not exist.
400 InvalidInstanceType.ValueUnauthorized The specified InstanceType is not authorized. The error message returned because you are not authorized to use the specified instance type.
400 InvalidInstanceType.ValueNotSupported The specified InstanceType does not exist or beyond the permitted range. The error message returned because the specified instance type does not exist or you are not authorized to operate on the instance type.
500 InternalError The request processing has failed due to some unknown error, exception or failure. The error message returned because an internal error has occurred. Try again later. If the problem persists, submit a ticket.
404 BillingMethodNotFound The account has not chosen any billing method. The error message returned because no billing method is selected for this account.
403 OperationDenied.NoStock The specified instance is out of usage. The error message returned because the specified instance is out of stock.
400 InvalidBillingMethod.ValueNotSupported The operation is not permitted due to an invalid billing method of the instance. The error message returned because the operation is not supported due to the invalid billing method for the instance.
400 InvalidInstanceId.Released The specified instance has been released. The error message returned because the instance has been released.
400 InvalidInstance.PurchaseNotFound The specified instance has no purchase history. The error message returned because the order record for this instance does not exist.
400 InvalidInstanceType.NotSupported The specified InstanceType is not Supported. The error message returned because the specified instance type is not supported.
400 OrderCreationFailed Order creation failed, please check your params and try it again later. The error message returned because the order fails to be created. Check your parameters and try again later.
400 Throttling You have made too many requests within a short time; your request is denied due to request throttling. The error message returned because your request is denied due to request throttling. Try again later.
400 Account.Arrearage Your account has an outstanding payment. The error message returned because your account has overdue payments.
403 InvalidUser.PassRoleForbidden The RAM user does not have privilege to pass a role. The error message returned because the RAM user attempts to assign RAM roles. RAM users do not have the corresponding permissions.
400 InvalidInstanceId.NotFound The specified InstanceId does not exist. The error message returned because the specified value of the InstanceId parameter does not exist.
400 InvalidRebootTime.MalFormed The specified rebootTime is not valid. The error message returned because the specified value of the RebootTime parameter is invalid.
400 InvalidRebootTime.ValueNotSupported The specified RebootTime is not valid. The error message returned because the specified value of the RebootTime parameter is invalid.
403 ImageNotSupportInstanceType The specified image does not support the specified InstanceType. The error message returned because the specified image cannot be used for the specified instance type.
403 InstanceType.Offline %s The error message returned because the instance type is phased-out or is insufficient.
400 IdempotenceParamNotMatch Request uses a client token in a previous request but is not identical to that request. The error message returned because the specified ClientToken in this request is not identical to the one used in the previous request.
403 IncorrectInstanceStatus The current status of the resource does not support this operation. The error message returned because the operation is not supported while the resource is in the current state.
400 IdempotenceParamNotMatch %s The error message returned because the Idempotence parameters do not match.
400 InvalidInstanceChargeType.ValueNotSupported %s The error message returned because the charge type is not supported. Check related information and try again.
400 InvalidStatus.NotStopped Instance status must be stopped. The error message returned because the instance is not in the Stopped state. The operation can be performed only when the instance is in the Stopped state.
400 InvalidAction %s The error message returned because this operation is invalid.
400 InstanceDowngrade.QuotaExceed Quota of instance downgrade is exceed. The error message returned because this operation is denied due to the instance downgrade that has reached the quota.
400 InvalidInstanceType.ValueNotSupported %s The error message returned because this operation cannot be performed on instances of the specified instance type.
403 InvalidParameter.InstanceId %s The error message returned because the specified value of the InstanceId parameter is invalid.
400 InvalidParameter %s The error message returned because the specified parameter value is invalid.
403 OperationDenied %s The error message is returned because the operation is denied.
403 ImageNotSupportInstanceType The specified instanceType is not supported by instance with marketplace image. The error message returned because the specified Alibaba Cloud Marketplace image does not support the instance type.
403 InvalidInstanceStatus The current status of the instance does not support this operation. The error message returned because this operation is not supported while the instance is in the current state.
403 InvalidInstance.PreInstanceExpired Instance business status is not Expired The error message returned because the current instance has expired.
403 InvalidInstance.EipNotSupport The special instance with eip not support operate, please unassociate eip first. The error message returned because the operation is not supported while an EIP has been bound to this instance. Unbind the EIP first.
400 OperationDenied The current user does not support this operation. The error message returned because the specified account does not support this operation.
403 OperationDenied.LocalDiskUnsupported The configuration change is not allowed when the specified instance has local disks mounted. The error message returned because the instance type of instances with local disks attached cannot be changed.
403 OperationDenied.NoStock The resource is out of stock in the specified zone. Please try other types, or choose other regions and zones. The error message returned because the specified resource is unavailable in the specified zone. Try with other types, or choose other regions or zones.
400 LastOrderProcessing The previous order is still processing, please try again later. The error message returned because the order is being processed. Try again later.
403 InvalidOperation.Ipv4CountExceeded %s The error message returned because the maximum number of IPv4 addresses has been reached.
403 InvalidOperation.Ipv6CountExceeded %s The error message returned because the maximum number of IPv6 addresses has been reached.
403 InvalidOperation.Ipv6NotSupport %s The error message returned because the IPv6 address does not support the current operation.
500 InternalError The request processing has failed due to some unknown error. The error message returned because an internal error has occurred. Try again later. If the problem persists, submit a ticket.

For a list of error codes, visit the API Error Center.