Use DescribeInstanceModificationPrice to query the price of upgrading subscription instance configurations - Elastic Compute Service - Alibaba Cloud - Elastic Compute Service

Queries the price of the target instance type and the price of new subscription data disks when you upgrade a subscription ECS instance that has not expired.

Operation description

Supports querying only the price for upgrading subscription ECS instances that have not expired. Querying the price for downgrading instances is not supported.
Does not support querying the price for changing the configurations of pay-as-you-go ECS instances. Because the price of a pay-as-you-go ECS instance after a configuration change is the same as the price of a new instance, you can call DescribePrice to query the latest price of ECS instances.
Before upgrading an instance, call DescribeResourcesModification to query the instance types to which you can upgrade in a specified zone.

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:DescribeInstanceModificationPrice

get

*Instance

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

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID. You can call DescribeRegions to query the most recent region list.	cn-hangzhou
InstanceId	string	Yes	The instance ID for which you want to query the upgrade price.	i-bp1f2o4ldh8l****
InstanceType	string	No	The target instance type to which you want to upgrade. Call DescribeResourcesModification to query the instance types to which you can upgrade in a specified zone. Note When you send a request, the instance type parameter (InstanceType) and the data disk parameters (DataDisk.N.*) cannot both be empty. You must specify at least one of them.	ecs.g6e.large
SystemDisk.Category	string	No	The system disk type. This parameter is required only when you upgrade from a retired instance type to an available instance type and change a non-I/O optimized instance to an I/O optimized instance. For more information about instance types, see Instance families and Retired instance types. Valid values: cloud_efficiency: ultra disk. cloud_ssd: standard SSD. Default value: none.	cloud_ssd
SystemDisk	object	No	The system disk modification settings.
Category	string	No	The system disk type.
PerformanceLevel	string	No	The performance level of the system disk.	PL0
Size	integer	No	The size of the system disk.	40
DataDisk	array<object>	No	The data disk type information.
	object	No	The data disk type information.
PerformanceLevel	string	No	The performance level of the data disk when the disk type is enterprise SSD (ESSD). The value of N must be the same as the N in `DataDisk.N.Category=cloud_essd`. Valid values: PL0: maximum random read/write IOPS of 10,000 per disk. PL1: maximum random read/write IOPS of 50,000 per disk. PL2: maximum random read/write IOPS of 100,000 per disk. PL3: maximum random read/write IOPS of 1,000,000 per disk. Default value: PL1. For information about how to choose an ESSD performance level, see ESSDs.	PL1
Size	integer	No	The capacity of the data disk. The value of N ranges from 1 to 16. Unit: GiB. Valid values: cloud_efficiency: 20 to 32768. cloud_ssd: 20 to 32768. cloud_essd: The valid values depend on the value of `DataDisk.N.PerformanceLevel`. PL0: 1 to 32768. PL1: 20 to 32768. PL2: 461 to 32768. PL3: 1261 to 32768. cloud: 5 to 2000. Default value: the minimum capacity size for the specified data disk type.	100
Category	string	No	The data disk type. Specify this parameter when you want to query the price of a new subscription data disk to attach to an ECS instance. The value of N ranges from 1 to 16. Valid values: cloud_efficiency: ultra disk. cloud_ssd: standard SSD. cloud_essd: enterprise SSD (ESSD). cloud: basic disk. Default value: none. Note When you send a request, the instance type parameter (InstanceType) and the data disk parameters (DataDisk.N.*) cannot both be empty. You must specify at least one of them.	cloud_essd
DiskId	string	No	The data disk ID. If DiskId is empty, a new data disk is added. If DiskId is not empty, an existing data disk is modified.	d-bf4rupt9****
ImageId	string	No	The image ID.	aliyun_2_1903_x64_20G_alibase_20200324.vhd
InternetMaxBandwidthOut	integer	No	The maximum outbound public bandwidth.	10
ISP	string	No	The Internet service provider (ISP).	BGP
InternetChargeType	string	No	Transforms the network billing method. Valid values: ● PayByBandwidth: pay-by-bandwidth. ● PayByTraffic: pay-by-traffic.	PayByTraffic
StartTime	string	No	The start time of the temporary bandwidth upgrade. The time follows the ISO 8601 standard in UTC. This parameter takes effect only when InternetMaxBandwidthOut is not empty.	2025-12-05T22:40Z
EndTime	string	No	The end time of the temporary bandwidth upgrade. The time follows the ISO 8601 standard in UTC. This parameter takes effect only when InternetMaxBandwidthOut is not empty.	2025-12-06T22Z

Response elements

Element	Type	Description	Example
	object
RequestId	string	The request ID.	A3DC3196-379B-4F32-A2C5-B937134FAD8A
PriceInfo	object	The price information, which is of the PriceInfo type and includes the price and promotion rule details.
Rules	object
Rule	array<object>	The promotion rules.
	object
Description	string	The description of the promotion rule.	Upgrade discount
RuleId	integer	The promotion ID.	1234567890
Price	object	The price details.
OriginalPrice	number	The original price.	175.200
DiscountPrice	number	The discount amount.	61.320
Currency	string	The currency unit. Valid values: Alibaba Cloud China site: CNY. Alibaba Cloud International site: USD.	CNY
TradePrice	number	The final price, which equals the original price minus the discount.	113.880
DetailInfos	object
DetailInfo	array<object>	The detailed price information for each configuration item. Note Returned only when ResourceType = instance.
	array<object>	The detailed price information for each configuration item.
Resource	string	The configuration item name. Valid values: instanceType: instance type. bandwidth: bandwidth. image: image. systemDisk: system disk. dataDisk: data disk.	instanceType
OriginalPrice	number	The original price.	4368
DiscountPrice	number	The discounted price.	655.2
TradePrice	number	The transaction price.	3712.8
SubRules	object
Rule	array<object>	The subset of pricing rules.
	object	The subset of pricing rules.
Description	string	The description of the pricing rule subset.	Purchase for 1 year and enjoy an 85% discount on the official website price
RuleId	integer	The promotion rule ID.	315716429631488
RelatedPrice	object	The related price information.
MarketplaceImagePrice	object	The price of the Alibaba Cloud Marketplace image.
Currency	string	The currency unit. Alibaba Cloud China site: CNY. Alibaba Cloud International site: USD.	CNY
OriginalPrice	number	The original price.	100
DiscountPrice	number	The discount amount.	0
TradePrice	number	The final price, which equals the original price minus the discount.	100

Examples

Success response

JSON format

{
  "RequestId": "A3DC3196-379B-4F32-A2C5-B937134FAD8A",
  "PriceInfo": {
    "Rules": {
      "Rule": [
        {
          "Description": "Upgrade discount",
          "RuleId": 1234567890
        }
      ]
    },
    "Price": {
      "OriginalPrice": 175.2,
      "DiscountPrice": 61.32,
      "Currency": "CNY",
      "TradePrice": 113.88,
      "DetailInfos": {
        "DetailInfo": [
          {
            "Resource": "instanceType",
            "OriginalPrice": 4368,
            "DiscountPrice": 655.2,
            "TradePrice": 3712.8,
            "SubRules": {
              "Rule": [
                {
                  "Description": "15% discount for a one-year subscription",
                  "RuleId": 315716429631488
                }
              ]
            }
          }
        ]
      }
    },
    "RelatedPrice": {
      "MarketplaceImagePrice": {
        "Currency": "CNY",
        "OriginalPrice": 100,
        "DiscountPrice": 0,
        "TradePrice": 100
      }
    }
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	MissingParameter.InstanceTypeOrDataDisk	You must specify the parameter InstanceType or DataDisk.	Either the instance type or the data disk parameter must be specified. Both cannot be empty.
400	InvalidSystemDiskCategory.ValueNotSupported	The specified parameter "SystemDisk.Category" is not valid.	The specified parameter system disk specification is invalid.
400	InvalidDiskCategory.Missing	The DataDisk.1.Category parameter that is mandatory for processing the request is not provided.	The mandatory parameter DataDiskCategory is not provided.
400	InvalidDataDiskCategory.ValueNotSupported	The specified parameter "DataDisk.n.Category" is not valid.
400	InvalidDiskCategory.ValueNotSupported	The specified parameter "DiskCategory" is not valid.	The specified cloud disk type DiskCategory is invalid.
400	InvalidDataDiskSize.ValueNotSupported	The specified DataDisk.n.Size beyond the permitted range.	The specified DataDisk.n.Size parameter is out of the valid range.
400	InvalidPerformanceLevel.Malformed	The specified parameter DataDisk.n.PerformanceLevel is not valid.	The specified PerformanceLevel parameter is invalid.
400	InvalidDiskSize.TooSmall	Specified disk size is too small when choose PL0 of cloud_essd.
400	OperationDenied.PerformanceLevelNotMatch	The specified DataDisk.n.PerformanceLevel and DataDisk.n.Size do not match.	The specified performance level does not match the disk size.
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	InvalidAction.WithActiveElasticUpgrade	The instance has active Elastic Upgrade.
400	PriceNotFound	The price of your queried resource is not available now, please try other resources.	The price of the specified resource does not exist. Modify the parameter value and try again later.
400	InvalidBandwidth.ValueNotSupported	Instance upgrade bandwidth of temporary not allow less then existed.	The specified bandwidth value is not supported.
400	InvalidParameter.InstanceTypeAndNetworkConflict	The current operation does not allow both InstanceType and network modification parameter to be set.	The instance type and network change parameters cannot be set at the same time for the current request.
400	InvalidParameter.InstanceTypeAndImageConflict	The current operation does not allow both InstanceType and ImageId parameter to be set.	The current request cannot set InstanceType and ImageId parameters at the same time.
400	InvalidParameter.InstanceTypeAndDiskConflict	The current operation does not allow both InstanceType and Disk parameter to be set.	The InstanceType and Disk parameters cannot be set at the same time in the current request.
400	InvalidParameter.NetworkAndImageConflict	The current operation does not allow both network modification parameter and ImageId to be set.	The current request cannot set network changes and ImageId parameters at the same time.
400	InvalidParameter.NetworkAndDiskConflict	The current operation does not allow both network modification parameter and disk parameter to be set.	The current request cannot set the network change and the Disk parameter at the same time.
400	InvalidParameter.ImageAndDiskConflict	The current operation does not allow both ImageId and DataDisk parameter to be set.	The ImageId and Disk parameters cannot be specified at the same time in the current request.
400	InvalidParameter.CategoryAndSizeConflict	The current operation does not allow both Category and Size parameter to be set.	The Category and Size parameters cannot be specified at the same time in the current request.
400	MissingParameter.Instance	The instance modification parameter can not be empty.	The parameter of the instance configuration cannot be empty.
500	InternalError	The request processing has failed due to some unknown error, exception or failure.	An internal error has occurred. Try again later.
403	InvalidParameter.ResourceOwnerAccount	ResourceOwnerAccount is Invalid.	The specified ResourceOwnerAccount parameter is invalid.
403	ChargeTypeViolation	PostPaid instance do not support this operation.
403	InvalidInstanceType.NotSupportUpgrade	The specified InstanceType can only be downgraded. This API supports querying prices only of InstanceType that can be upgraded.	The specified instance type can be used only for a configuration downgrade of the specified instance, and this API operation can be used to query pricing information about instance types only for instance configuration upgrades. We recommend that you call the DescribeResourcesModification operation to query the instance types available for instance configuration upgrades.
403	InstanceExpired	The PrePaid instance has been expired.	The subscription instance has expired. Renew the instance before performing this operation.
403	Throttling.User	Request was denied due to user flow control.
403	Throttling	Request was denied due to request throttling.
403	InstanceType.Offline	The specified InstanceType has been offline	The specified instance type is retired. Select another instance type.
403	RegionUnauthorized	There is no authority to create instance in the specified region.	You are not authorized to create instances in the specified region.
403	InvalidSystemDiskCategory.ValueNotSupported	The specified parameter SystemDisk.Category is not valid.	The specified SystemDisk.Category value is not supported.
403	InvalidDataDiskCategory.ValueNotSupported	The specified Category of Data Disk is not valid.	The specified data disk type is not supported.
403	OperationDenied.PerformanceLevelNotMatch	The specified PerformanceLevel and disk size do not match.	The specified performance level and disk size do not match.
404	InvalidRegionId.NotFound	The RegionId provided does not exist in our records.	Region information error
404	InvalidResourceGroup.NotFound	The ResourceGroup provided does not exist in our records.	The specified resource group does not exist.
404	InvalidInstanceId.NotFound	The specified InstanceId does not exist.	The specified instanceId is invalid.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.