All Products
Search
Document Center

Elastic Compute Service:ModifyPrepayInstanceSpec

Last Updated:Oct 23, 2026

Modifies ECS instance type of a subscription Elastic Compute Service (ECS) instance. This operation supports upgrading or downgrading ECS instance type. The modified instance type takes effect for the entire lifecycle of ECS instance.

Operation description

Before calling this operation, make sure that you fully understand the billing methods, pricing, and refund rules for downgrades of Elastic Compute Service (ECS).

This operation is asynchronous. Wait 5 to 10 seconds for the configuration change to complete. Before upgrading or downgrading ECS instance type of a subscription ECS instance, you can call the DescribeResourcesModification operation to query ECS instance types available for the current instance.

Precautions

  • If the NVMe property of the original instance type is different from that of the target instance type (the NvmeSupport field in DescribeInstanceTypes) and the operating system is Windows (the OSType field in DescribeInstances), you must complete the operations described in Preventive measures before you upgrade or downgrade the instance type.

  • You cannot modify the instance type of an expired instance. You can renew the instance 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 payment method. Used vouchers are not refunded.

    • The new instance type takes effect after you start the instance.

  • 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 or downgrade. For valid values, see Instance families or call the DescribeInstanceTypes operation.

ecs.g5.xlarge

OperatorType

string

No

The operation type. Valid values:

Note

You do not need to specify this parameter. The system automatically determines whether to upgrade or downgrade the instance type. If you specify this parameter, follow these rules:

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

  • downgrade: downgrades the instance type. If 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 preceding operation description section.

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 value, but you must make sure that the value is unique among different requests. The token 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 enable automatic payment when you upgrade the instance type. Valid values:

  • true: enables automatic payment.

  • false: generates the order without deducting fees.

Default value: true.

Note
  • When automatic payment is enabled, you must ensure that your payment method balance is sufficient. Otherwise, an abnormal order is generated and can only be canceled.

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

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

true

MigrateAcrossZone

boolean

No

Specifies whether to allow cross-cluster instance type upgrade. Valid values:

  • true: yes.

  • false: no.

Default value: false.

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

VPC-connected instances: For retired instance types, when you upgrade a non-I/O optimized instance to an I/O optimized instance, the disk device names and software authorization codes of the ECS instance change. For Linux instances, basic disks (cloud) are identified as xvda or xvdb, and 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 upgrade from a retired instance type to a normally sold instance family and upgrade a non-I/O optimized instance type to an I/O optimized instance type.

cloud_efficiency

RebootTime

string

No

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

2018-01-01T12:05Z

EndTime

string

No

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

2018-01-01T12:05Z

RebootWhenFinished

boolean

No

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

  • true: yes.

  • false: no.

Default value: false.

Note

If the instance is in the Stopped state, it remains in the Stopped state and no action is performed even if you set RebootWhenFinished to true.

false

ModifyMode

string

No

Note

This parameter is not available.

Valid values:

  • Offline :

    Offline modification.

  • Online :

    Online modification.

null

Disk

array<object>

No

Note

This parameter is not available.

object

No

Note

This parameter is not available.

Category

string

No

Note

This parameter is not available.

null

DiskId

string

No

Note

This parameter is not available.

null

PerformanceLevel

string

No

Note

This parameter is not available.

null

Response elements

Element

Type

Description

Example

object

OrderId

string

The ID of the generated order.

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. Failed to create the order.
400 Throttling You have made too many requests within a short time; your request is denied due to request throttling. The request is throttled.
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. This operation is supported 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 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 capacity of the specified disk category exceeds the quota in the zone. Details: %s.
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. 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. The current CPU topology type does not support hot specification changes.
400 InvalidInstanceType.NotSupportCpuOptionsNestedVirtualization The specified instance type does not support CpuOptions.NestedVirtualization: %s. The specified instance type does not support CpuOptions.NestedVirtualization value.
400 OperationDenied.UnfinishedOrder The current instance has unfinished refundOrder, this operation is denied. The instance has a pending refund order. Wait and try again later.
400 InvalidStatus.InstanceLocked The specified instance is locked The specified instance is locked.
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 marketplace image is not authorized. Please verify the marketplace image authorization and try again.
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 The current operation is not supported for IPv6.
403 InvalidOperation.Ipv4NotSupport %s
403 InvalidInstance.NotFoundSystemDisk The specified instance has no system disk.
403 InvalidInstanceType.NotSupportDiskCategory The specified InstanceType does not support the specified disk category. Please call DescribeAvailableResource to query the supported disk category and try again.
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 The number of Elastic Network Interface (Elastic Network Interface (ENI)) controller (NIC) queues exceeds the upper limit. For more information, see the actual value of the %s placeholder in the fault message.
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 The number of Elastic Network Interface (Elastic Network Interface (ENI)) controller (NIC) queues is incorrect. For more information, see the actual value of the %s placeholder in the fault 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 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 current operation is not supported because the specified resource is/has a detached system disk. Please attach the disk or verify the resource state and try again.
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. The specified disk category is not supported by the instance type.
403 InvalidOperation.InstanceTypeSecureBootUnsupported The instance type does not support secure boot. The instance type does not support secure boot.
403 InvalidOperation.InstanceTypeNotSupportEniTrunking The specified instance type does not support ENI trunking operation. The specified instance type does not support ENI trunking operation.
403 InvalidStatus.InstanceStatus The specified instance status does not support this operation, expected status is Running or Stopped. The instance is in a state that does not support the current operation. The operation can be performed only when the instance is in the Running or Stopped state.
403 InvalidClientToken.Malformed The specified clientToken is improperly formatted. It must contain only ASCII characters and must not exceed 64 characters in length. The specified clientToken is improperly formatted. It must contain only ASCII characters and must not exceed 64 characters in length.
403 IncorrectDiskStatus This operation is not supported for the current disk status. The disk must be In Use or Available to continue. The disk status does not support the current operation. The disk status must be InUse or Available.
403 InvalidParameter.NotMatch %s A specified parameter is invalid. Check whether parameter conflicts exist.
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.