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

Retrieves the pricing for upgrading an active subscription ECS instance to a target instance type and for adding a subscription data disk.

Operation description

You can query pricing for upgrading unexpired subscription ECS instances, but not for downgrading them.
You cannot query prices for resizing pay-as-you-go ECS instances. Because a resized instance is priced the same as a new one, call DescribePrice to get the current price.
Before upgrading an instance, call DescribeResourcesModification to find the instance types available for an upgrade in a specific availability 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 the DescribeRegions operation to get the latest list of Alibaba Cloud regions.	cn-hangzhou
InstanceId	string	Yes	The ID of the instance for which to query the modification price.	i-bp1f2o4ldh8l****
InstanceType	string	No	The target instance type for the instance upgrade. Call the DescribeResourcesModification operation to query the instance types available for upgrade in the specified availability zone. Note You must specify at least one of the `InstanceType` and `DataDisk.N.*` parameters.	ecs.g6e.large
SystemDisk.Category	string	No	The category of the system disk. This parameter is required only when you upgrade a non-I/O optimized instance of a retired instance type to an I/O optimized instance of an available instance type. For more information about instance types, see instance family and retired instance types. Valid values: `cloud_efficiency`: Ultra Disk `cloud_ssd`: Standard SSD Default value: None.	cloud_ssd
DataDisk	array<object>	No
	object	No	The data disk configuration.
PerformanceLevel	string	No	The performance level of the ESSD. This parameter is valid only when DataDisk.N.Category is set to cloud_essd. The value of N must match the N in DataDisk.N.Category. Valid values: - PL0: up to 10,000 random read/write IOPS per disk. - PL1: up to 50,000 random read/write IOPS per disk. - PL2: up to 100,000 random read/write IOPS per disk. - PL3: up to 1,000,000 random read/write IOPS per disk. Default value: PL1. For more information about ESSD performance levels, see [ESSDs](~~122389~~).	PL1
Size	integer	No	The size of data disk N in GiB, where N is an integer from 1 to 16. The value range varies based on the disk category: - `cloud_efficiency` (Ultra Disk): 20 to 32768. - `cloud_ssd` (Standard SSD): 20 to 32768. - `cloud_essd`: The value range varies based on the value of `DataDisk.N.PerformanceLevel`. - PL0: 1 to 32768. - PL1: 20 to 32768. - PL2: 461 to 32768. - PL3: 1261 to 32768. - `cloud` (Basic Disk): 5 to 2000. Default value: The minimum size supported by the specified data disk category.	100
Category	string	No	The category of data disk N, where N is an integer from 1 to 16. Use this parameter to query the price of adding a new data disk to the instance. Valid values: - `cloud_efficiency`: Ultra Disk - `cloud_ssd`: Standard SSD - `cloud_essd`: ESSD - `cloud`: Basic Disk Default value: None.	cloud_essd
DiskId	string	No		d-bf4rupt9****

Response elements

Element	Type	Description	Example
	object
RequestId	string	The request ID.	A3DC3196-379B-4F32-A2C5-B937134FAD8A
PriceInfo	object	Price information, including price details and promotional rules.
Rules	object
Rule	array<object>	A list of promotional rules.
	object
Description	string	The description of the rule.	升级优惠
RuleId	integer	The rule 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. Valid values: `CNY`: For the China site. `USD`: For the international site.	CNY
TradePrice	number	The final price (original price - discount).	113.880
DetailInfos	object
DetailInfo	array<object>	A list of price details for each resource in the configuration. Note This parameter is returned only when `ResourceType` is set to `instance`.
	array<object>	Price details for a single resource.
Resource	string	The resource type. 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 discount amount.	655.2
TradePrice	number	The final price.	3712.8
SubRules	object
Rule	array<object>	Pricing rule subsets.
	object	A single pricing rule subset.
Description	string	The rule subset description.	买满1年，立享官网价格8.5折优惠
RuleId	integer	The rule ID.	315716429631488
RelatedPrice	object
MarketplaceImagePrice	object
Currency	string		CNY
OriginalPrice	number		100
DiscountPrice	number		0
TradePrice	number		100

Examples

Success response

JSON format

{
  "RequestId": "A3DC3196-379B-4F32-A2C5-B937134FAD8A",
  "PriceInfo": {
    "Rules": {
      "Rule": [
        {
          "Description": "升级优惠",
          "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": "买满1年，立享官网价格8.5折优惠",
                  "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.
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.
400	InvalidPerformanceLevel.Malformed	The specified parameter DataDisk.n.PerformanceLevel is not valid.
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.
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.
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.
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.
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.