ModifyPrepayInstanceSpec -

Upgrades or downgrades the instance type of a subscription Elastic Compute Service (ECS) instance. The new instance type takes effect for the remaining lifecycle of the instance.

Usage notes

Before you call this operation, we recommend that you familiarize yourself with the billing methods, pricing schedule, and refund rules of ECS. For more information, see Refund rules for real-time configuration downgrade.

Before you change the instance type of a subscription instance, you can call the DescribeResourcesModification operation to query the instance types to which you can change the instance. You can use ECS SDK for Python to query the instance types to which you can change. For more information, see Query available resources for configuration changes.

Take note of the following items:

You cannot change the instance type of an expired instance. You can renew the instance and try again.
When you downgrade the instance type of an instance, take note of the following items:
- The instance must be in the Stopped (Stopped) state.
- The price difference is refunded to the payment account you used. Vouchers that have been redeemed are not refundable.
The operation is asynchronous. It takes 5 to 10 seconds for the instance type to change. Then, restart the instance by calling the RebootInstance operation or by using the ECS console for the instance type change to take effect. If you restart only the operating system of the instance, the instance type change does not take effect.
- If the instance is in the Stopped state, you need only to start the instance. You do not need to restart the instance after it enters the Running state.
- If RebootWhenFinished is set to true for the instance, you do not need to manually restart the instance.

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	Yes	ModifyPrepayInstanceSpec	The operation that you want to perform. Set the value to ModifyPrepayInstanceSpec.
InstanceId	String	Yes	i-bp67acfmxazb4ph****	The instance ID.
RegionId	String	Yes	cn-hangzhou	The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.
InstanceType	String	Yes	ecs.g5.xlarge	The new instance type. For information about available instance types, see Instance families or call the DescribeInstanceTypes operation.
OperatorType	String	No	upgrade	The type of the operation. Valid values: Note This parameter is optional. The system can define the operation type. If you want to specify this parameter, take note of the following rules: upgrade: upgrades the instance type. Make sure that the balance in your account is sufficient. downgrade: downgrades the instance type. When the new instance type specified by `InstanceType` has lower specifications than the current instance type, set `OperatorType` to downgrade. Note For more information about the precautions on upgrading or downgrading instance types, see the preceding "Usage notes" section of 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 the value is unique among different requests. The token 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. Valid values: true: The payment is automatically completed. Note Make sure that your account balance is sufficient. Otherwise, your order becomes invalid. If your account balance is insufficient, you can set `AutoPay` to `false` to generate an unpaid order. Then, you can log on to the ECS console to pay for the order. false: An order is generated but no payment is made. Default value: true. When `OperatorType` is set to `downgrade`, `AutoPay` is ignored.
MigrateAcrossZone	Boolean	No	false	Specifies whether cross-cluster instance type upgrades are supported. Default value: false. When you set `MigrateAcrossZone` to `true` and you upgrade the instance based on the returned information, take note of the following items: Instances of the classic network type: For retired instance types, the private IP address, disk device names, and software license codes of a non-I/O optimized instance change when you upgrade the instance to an I/O optimized instance. For Linux instances, basic disks (cloud) are identified as xvd* such as xvda and xvdb. Ultra disks (cloud_efficiency) and standard SSDs (cloud_ssd) are identified as vd* such as vda and vdb. For instance families that can be purchased, the private IP address of the instance changes when you change the instance type of the instance. Instances of the Virtual Private Cloud (VPC) type: For retired instance types, when a non-I/O optimized instance is upgraded to an I/O optimized instance, the disk device names and software license codes of the instance change. For Linux instances, basic disks (cloud) are identified as xvd* such as xvda and xvdb. Ultra disks (cloud_efficiency) and standard SSDs (cloud_ssd) are identified as vd* such as vda and vdb.
SystemDisk.Category	String	No	cloud_efficiency	The new category of the system disk. This parameter is valid only when you upgrade an instance from a retired instance type to an available instance type or when you upgrade a non-I/O optimized instance to an I/O optimized instance. For more information, see Retired instance types and Instance families. Valid values: cloud_efficiency: ultra disk. cloud_ssd: standard SSD.
RebootTime	String	No	2018-01-01T12:05Z	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:05Z	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 instance type is changed. Valid values: true: restarts the instance immediately after the instance type is changed. false: does not restart the instance immediately after the instance type is changed. Default value: false. Note If the instance is in the Stopping state, the instance state remains unchanged and no operations are performed regardless of whether `RebootWhenFinished` is set to true.
ModifyMode	String	No	null	Note This parameter is not publicly available.
Disk.N.DiskId	String	No	null	Note This parameter is not publicly available.
Disk.N.Category	String	No	null	Note This parameter is not publicly available.
Disk.N.PerformanceLevel	String	No	null	Note This parameter is not publicly available.

Response parameters

Parameter	Type	Example	Description
OrderId	String	1234567890	The order ID.
RequestId	String	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E	The request ID.

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

HTTP/1.1 200 OK
Content-Type:application/xml

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

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

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

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidInstanceType.ValueUnauthorized	The specified InstanceType is not authorized.	You are not authorized to use the instance type.
400	InvalidInstanceType.ValueNotSupported	The specified InstanceType does not exist or beyond the permitted range.	The instance type is not found, or you are not authorized to manage instances of the 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 is not found.
400	InvalidInstanceType.NotSupported	The specified InstanceType is not Supported.	Invalid InstanceType value.
400	OrderCreationFailed	Order creation failed, please check your params and try it again later.	The order cannot be created. Modify your parameter settings and try again.
400	Throttling	You have made too many requests within a short time; your request is denied due to request throttling.	Your request is denied due to throttling. Try again later.
400	Account.Arrearage	Your account has an outstanding payment.	You have unpaid orders in your account.
400	InvalidInstanceId.NotFound	The specified InstanceId does not exist.	This instance is not found. Check whether the specified instance ID is valid.
400	InvalidRebootTime.MalFormed	The specified rebootTime is not valid.	Invalid RebootTime value.
400	InvalidRebootTime.ValueNotSupported	The specified RebootTime is not valid.	The specified restart time 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	IdempotenceParamNotMatch	%s	The idempotent parameters do not match.
400	InvalidInstanceChargeType.ValueNotSupported	%s	The specified billing method is not supported.
400	InvalidStatus.NotStopped	Instance status must be stopped.	The operation can be performed only when the instance is in the Stopped state.
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 is exceeded.
400	InvalidInstanceType.ValueNotSupported	%s	The instance type does not support this operation.
400	InvalidParameter	%s	Invalid parameter value.
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 VPC. You cannot create ECS instances that have low specifications in the VPC.
400	InvalidAction.WithActiveElasticUpgrade	The instance has active Elastic Upgrade.	The operation cannot be performed on the instance while the configurations of the instance are being temporarily upgraded. The configurations of the instance go through a temporary upgrade if the ModifyPrepayInstanceSpec operation is called with EndTime set.
400	QuotaExceed.DiskCapacity	The used capacity of disk type has exceeded the quota in the zone, %s.	The maximum capacity of disks that belong to the specified disk category is exceeded in the zone. You can go to the Quota Center to view and increase the disk capacity quota.
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.
403	OperationDenied.NoStock	The specified instance is out of usage.	The resources of the specified instance type are insufficient.
403	InvalidUser.PassRoleForbidden	The RAM user does not have privilege to pass a role.	Resource Access Management (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 cannot be performed on the instance 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.	The operation cannot be performed on the resource in the current state.
403	InvalidParameter.InstanceId	%s	Invalid InstanceId value.
403	OperationDenied	%s	The operation is denied.
403	ImageNotSupportInstanceType	The specified instanceType is not supported by instance with marketplace image.	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 operation cannot be performed on the instance in the current state.
403	InvalidInstance.EipNotSupport	The special instance with eip not support operate, please unassociate eip first.	The operation cannot be performed on the instance while an elastic IP address (EIP) is associated with the instance. Disassociate the EIP first.
403	OperationDenied.LocalDiskUnsupported	The configuration change is not allowed when the specified instance has local disks mounted.	The instance types of instances that use local disks 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 specified resource is unavailable in the specified zone. Try other resource types or select other regions or zones.
403	InvalidOperation.Ipv4CountExceeded	%s	The maximum number of IPv4 addresses is exceeded.
403	InvalidOperation.Ipv6CountExceeded	%s	The maximum number of IPv6 addresses is exceeded.
403	InvalidOperation.Ipv6NotSupport	%s	IPv6 addresses do not support the operation.
403	InvalidInstance.NotFoundSystemDisk	The specified instance has no system disk.	The specified instance has no system disk attached. Make sure that the specified instance has a system disk attached. You can call the DescribeInstances operation to query the details of the specified instance.
403	InvalidInstanceType.NotSupportDiskCategory	The instanceType of the specified instance does not support this disk category.	The instance type specified by InstanceType does not support the disk category of the instance. 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 is exceeded. Try another region or instance type, or reduce the purchase quantity. You can go to the ECS console or the Quota Center to request a quota increase.
403	QuotaExceed.ElasticQuota	The number of the specified ECS instances has exceeded the quota of the specified instance type.	The maximum number of instances of the specified instance type in the region is exceeded. Try another region or instance type, or reduce the purchase quantity. You can go to the ECS console or the Quota Center to request a quota increase.
403	QuotaExceed.ElasticQuota	The number of vCPUs assigned to the ECS instances has exceeded the quota in the zone.	The maximum number of vCPUs for all instance types in the zone is exceeded. You can go to the ECS console or Quota Center to request a quota increase.
403	QuotaExceed.ElasticQuota	The number of the specified ECS instances has exceeded the quota of the specified instance type, or the number of vCPUs assigned to the ECS instances has exceeded the quota in the zone.	The maximum number of instances of the specified instance type in the region, or the maximum number of vCPUs for all instance types in the zone is exceeded. You can go to the ECS console or Quota Center to request a quota increase.
403	InvalidOperation.MaxEniQueueNumberExceeded	%s	The maximum number of queues per elastic network interface (ENI) is exceeded. For more information, see the return value of the %s placeholder in the error message.
403	InvalidOperation.ExceedInstanceTypeQueueNumber	%s	The maximum number of queues for all ENIs is exceeded. For more information, see the return value of the %s placeholder in the error message.
403	InvalidParameter.InvalidEniQueueNumber	%s	Invalid number of queues per ENI. For more information, see the return value of the %s placeholder in the error message.
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	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.
404	InvalidRegionId.NotFound	The specified RegionId does not exist.	Invalid RegionId value.
404	BillingMethodNotFound	The account has not chosen any billing method.	No billing method is selected for the Alibaba Cloud account.
500	InternalError	The request processing has failed due to some unknown error, exception or failure.	An internal error occurred. Try again later.
500	InternalError	The request processing has failed due to some unknown error.	An internal error occurred. Try again later.

For a list of error codes, see Service error codes.