Reservations - List By Billing Account
Lists the reservations in the billing account and the roll up counts of reservations group by provisioning states.
GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/{billingAccountName}/reservations?api-version=2024-04-01
GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/{billingAccountName}/reservations?api-version=2024-04-01&filter={filter}&orderBy={orderBy}&skiptoken={skiptoken}&refreshSummary={refreshSummary}&selectedState={selectedState}&take={take}
URI Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
|
billing
|
path | True |
string pattern: ^([0-9]+|([Pp][Cc][Nn]\.[A-Za-z0-9]+)|[0-9A-Fa-f]{8}-([0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}(:[0-9A-Fa-f]{8}-([0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}_[0-9]{4}(-[0-9]{2}){2})?)$ |
The ID that uniquely identifies a billing account. |
|
api-version
|
query | True |
string minLength: 1 |
The API version to use for this operation. |
|
filter
|
query |
string |
The filter query option allows clients to filter a collection of resources that are addressed by a request URL. |
|
|
order
|
query |
string |
The orderby query option allows clients to request resources in a particular order. |
|
|
refresh
|
query |
string |
To indicate whether to refresh the roll up counts of the reservations group by provisioning states |
|
|
selected
|
query |
string |
The selected provisioning state |
|
|
skiptoken
|
query |
number (float) |
The number of reservations to skip from the list before returning results |
|
|
take
|
query |
number (float) |
The number of reservations to return in API response. |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK |
Azure operation completed successfully. |
|
| Other Status Codes |
An unexpected error response. |
Security
azure_auth
Azure Active Directory OAuth2 Flow.
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
| Name | Description |
|---|---|
| user_impersonation | impersonate your user account |
Examples
reservationsListByBillingAccount
Sample request
GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/00000000-0000-0000-0000-000000000000:00000000-0000-0000-0000-000000000000_2019-05-31/reservations?api-version=2024-04-01&selectedState=Succeeded
Sample response
{
"nextLink": null,
"summary": {
"cancelledCount": 0,
"expiredCount": 0,
"expiringCount": 0,
"failedCount": 0,
"noBenefitCount": 0,
"pendingCount": 0,
"processingCount": 0,
"succeededCount": 1,
"warningCount": 0
},
"value": [
{
"name": "00000000-0000-0000-0000-000000000000",
"type": "microsoft.billing/billingAccounts/reservationOrders/reservations",
"id": "/providers/Microsoft.Billing/billingAccounts/00000000-0000-0000-0000-000000000000:00000000-0000-0000-0000-000000000000_2019-05-31/reservationOrders/00000000-0000-0000-0000-000000000001/reservations/00000000-0000-0000-0000-000000000000",
"location": "global",
"properties": {
"appliedScopeType": "Shared",
"archived": false,
"benefitStartTime": "2022-01-18T21:54:31.0741034Z",
"billingPlan": "Monthly",
"billingScopeId": "/subscriptions/eef82110-c91b-4395-9420-fcfcbefc5a47",
"displayName": "VirtualMachineSoftware_01-18-2022_13-51",
"displayProvisioningState": "Succeeded",
"effectiveDateTime": "0001-01-01T00:00:00Z",
"expiryDate": "2025-01-18",
"expiryDateTime": "2025-01-18T21:54:31.0741034Z",
"instanceFlexibility": "On",
"lastUpdatedDateTime": "0001-01-01T00:00:00.0000000",
"productCode": "20000000-0000-0000-0000-000000000005",
"provisioningState": "Succeeded",
"purchaseDate": "2022-01-18",
"purchaseDateTime": "2022-01-18T21:51:29.9063671Z",
"quantity": 1,
"renew": false,
"reservedResourceType": "VirtualMachineSoftware",
"skuDescription": "Sku description",
"term": "P3Y",
"userFriendlyAppliedScopeType": "Shared",
"userFriendlyRenewState": "Off",
"utilization": {
"aggregates": [
{
"grain": 1,
"grainUnit": "days",
"value": 0,
"valueUnit": "percentage"
},
{
"grain": 7,
"grainUnit": "days",
"value": 0,
"valueUnit": "percentage"
},
{
"grain": 30,
"grainUnit": "days",
"value": 0,
"valueUnit": "percentage"
}
],
"trend": "SAME"
}
},
"sku": {
"name": "mock_sku"
},
"tags": {
"key1": "value1",
"key2": "value2"
}
}
]
}
Definitions
| Name | Description |
|---|---|
|
Applied |
Type of the Applied Scope. |
|
created |
The type of identity that created the resource. |
|
Error |
The resource management error additional info. |
|
Error |
The error detail. |
|
Error |
Error response |
|
Extended |
Extended status definition properties |
|
Instance |
Turning this on will apply the reservation discount to other VMs in the same VM size group. Only specify for VirtualMachines reserved resource type. |
| Price |
The price. |
|
Renew |
The renew properties for a reservation. |
| Reservation |
The definition of the reservation. |
|
Reservation |
Properties specific to applied scope type. Not required if not applicable. Required and need to provide tenantId and managementGroupId if AppliedScopeType is ManagementGroup |
|
Reservation |
Represent the billing plans. |
|
Reservation |
Extended status information for the reservation. |
|
Reservation |
Properties of reservation merge |
|
Reservation |
The request for reservation purchase |
|
Reservation |
The property of reservation sku object. |
|
Reservations |
The list of reservations and summary of roll out count of reservations in each state. |
|
Reservation |
Properties of reservation split |
|
Reservation |
The status of the reservation. |
|
Reservation |
The roll up count summary of reservations in each state |
|
Reservation |
Properties of reservation swap |
|
Reservation |
The aggregate values of reservation utilization |
|
Sku |
The name of sku |
|
system |
Metadata pertaining to creation and last modification of the resource. |
AppliedScopeType
Type of the Applied Scope.
| Value | Description |
|---|---|
| Single |
Single |
| Shared |
Shared |
| ManagementGroup |
ManagementGroup |
createdByType
The type of identity that created the resource.
| Value | Description |
|---|---|
| User | |
| Application | |
| ManagedIdentity | |
| Key |
ErrorAdditionalInfo
The resource management error additional info.
| Name | Type | Description |
|---|---|---|
| info |
object |
The additional info. |
| type |
string |
The additional info type. |
ErrorDetail
The error detail.
| Name | Type | Description |
|---|---|---|
| additionalInfo |
The error additional info. |
|
| code |
string |
The error code. |
| details |
The error details. |
|
| message |
string |
The error message. |
| target |
string |
The error target. |
ErrorResponse
Error response
| Name | Type | Description |
|---|---|---|
| error |
The error object. |
ExtendedStatusDefinitionProperties
Extended status definition properties
| Name | Type | Description |
|---|---|---|
| subscriptionId |
string |
Subscription Id |
InstanceFlexibility
Turning this on will apply the reservation discount to other VMs in the same VM size group. Only specify for VirtualMachines reserved resource type.
| Value | Description |
|---|---|
| On |
On |
| Off |
Off |
Price
The price.
| Name | Type | Description |
|---|---|---|
| amount |
number (double) |
|
| currencyCode |
string |
The ISO 4217 3-letter currency code for the currency used by this purchase record. |
RenewPropertiesResponse
The renew properties for a reservation.
| Name | Type | Description |
|---|---|---|
| billingCurrencyTotal |
Currency and amount that customer will be charged in customer's local currency for renewal purchase. Tax is not included. |
|
| pricingCurrencyTotal |
Amount that Microsoft uses for record. Used during refund for calculating refund limit. Tax is not included. This is locked price 30 days before expiry. |
|
| purchaseProperties |
The request for reservation purchase |
Reservation
The definition of the reservation.
| Name | Type | Description |
|---|---|---|
| etag |
integer (int32) |
|
| id |
string (arm-id) |
Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}" |
| location |
string |
The location of the reservation. |
| name |
string |
The name of the resource |
| properties.appliedScopeProperties |
Properties specific to applied scope type. Not required if not applicable. Required and need to provide tenantId and managementGroupId if AppliedScopeType is ManagementGroup |
|
| properties.appliedScopeType |
string |
The applied scope type of the reservation. |
| properties.appliedScopes |
string[] |
The array of applied scopes of a reservation. Will be null if the reservation is in Shared scope |
| properties.archived |
boolean |
Indicates if the reservation is archived |
| properties.benefitStartTime |
string (date-time) |
This is the DateTime when the reservation benefit started. |
| properties.billingPlan |
The billing plan options available for this sku. |
|
| properties.billingScopeId |
string |
Subscription that will be charged for purchasing reservation or savings plan |
| properties.capabilities |
string |
Capabilities of the reservation |
| properties.displayName |
string |
The display name of the reservation |
| properties.displayProvisioningState |
string |
The provisioning state of the reservation for display, e.g. Succeeded |
| properties.effectiveDateTime |
string (date-time) |
The effective date time of the reservation |
| properties.expiryDate |
string |
The expiry date of the reservation |
| properties.expiryDateTime |
string (date-time) |
This is the date-time when the reservation will expire. |
| properties.extendedStatusInfo |
The message giving detailed information about the status code. |
|
| properties.instanceFlexibility |
Allows reservation discount to be applied across skus within the same auto fit group. Not all skus support instance size flexibility. |
|
| properties.lastUpdatedDateTime |
string (date-time) |
DateTime of the last time the reservation was updated. |
| properties.mergeProperties |
Properties of reservation merge |
|
| properties.productCode |
string |
Represents UPN |
| properties.provisioningState |
string |
The provisioning state of the reservation, e.g. Succeeded |
| properties.provisioningSubState |
string |
The provisioning state of the reservation, e.g. Succeeded |
| properties.purchaseDate |
string (date) |
This is the date when the reservation was purchased. |
| properties.purchaseDateTime |
string (date-time) |
This is the date-time when the reservation was purchased. |
| properties.quantity |
number (float) |
The number of the reservation. |
| properties.renew |
boolean |
The renew state of the reservation |
| properties.renewDestination |
string |
Reservation Id of the reservation which is purchased because of renew. Format of the resource Id is /providers/Microsoft.Capacity/reservationOrders/{reservationOrderId}/reservations/{reservationId}. |
| properties.renewProperties |
The renew properties for a reservation. |
|
| properties.renewSource |
string |
The renew source of the reservation |
| properties.reservedResourceType |
string |
The reserved source type of the reservation, e.g. virtual machine. |
| properties.reviewDateTime |
string (date-time) |
This is the date-time when the Azure Hybrid Benefit needs to be reviewed. |
| properties.skuDescription |
string |
The sku description of the reservation |
| properties.splitProperties |
Properties of reservation split |
|
| properties.swapProperties |
Properties of reservation swap |
|
| properties.term |
string |
The term of the reservation, e.g. P1Y |
| properties.userFriendlyAppliedScopeType |
string |
The applied scope type of the reservation for display, e.g. Shared |
| properties.userFriendlyRenewState |
string |
The renew state of the reservation for display, e.g. On |
| properties.utilization.aggregates |
The array of aggregates of a reservation's utilization |
|
| properties.utilization.trend |
string |
last 7 day utilization trend for a reservation |
| sku |
The sku information associated to this reservation |
|
| systemData |
Azure Resource Manager metadata containing createdBy and modifiedBy information. |
|
| tags |
object |
Tags for this reservation |
| type |
string |
The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts" |
ReservationAppliedScopeProperties
Properties specific to applied scope type. Not required if not applicable. Required and need to provide tenantId and managementGroupId if AppliedScopeType is ManagementGroup
| Name | Type | Description |
|---|---|---|
| displayName |
string |
Display name |
| managementGroupId |
string |
Fully-qualified identifier of the management group where the benefit must be applied. |
| resourceGroupId |
string |
Fully-qualified identifier of the resource group. |
| subscriptionId |
string |
Fully-qualified identifier of the subscription. |
| tenantId |
string |
Tenant ID where the reservation should apply benefit. |
ReservationBillingPlan
Represent the billing plans.
| Value | Description |
|---|---|
| Upfront |
Upfront |
| Monthly |
Monthly |
ReservationExtendedStatusInfo
Extended status information for the reservation.
| Name | Type | Description |
|---|---|---|
| message |
string |
The message giving detailed information about the status code. |
| properties |
Properties for extended status information |
|
| statusCode |
The status of the reservation. |
ReservationMergeProperties
Properties of reservation merge
| Name | Type | Description |
|---|---|---|
| mergeDestination |
string |
Reservation resource id Created due to the merge. Format of the resource id is /providers/Microsoft.Capacity/reservationOrders/{reservationOrderId}/reservations/{reservationId} |
| mergeSources |
string[] |
Resource ids of the source reservation's merged to form this reservation. Format of the resource id is /providers/Microsoft.Capacity/reservationOrders/{reservationOrderId}/reservations/{reservationId} |
ReservationPurchaseRequest
The request for reservation purchase
| Name | Type | Default value | Description |
|---|---|---|---|
| location |
string |
The Azure region where the reserved resource lives. |
|
| properties.appliedScopeProperties |
Properties specific to applied scope type. Not required if not applicable. Required and need to provide tenantId and managementGroupId if AppliedScopeType is ManagementGroup |
||
| properties.appliedScopeType |
Type of the Applied Scope. |
||
| properties.appliedScopes |
string[] |
List of the subscriptions that the benefit will be applied. Do not specify if AppliedScopeType is Shared. |
|
| properties.billingPlan |
Represent the billing plans. |
||
| properties.billingScopeId |
string |
Subscription that will be charged for purchasing reservation or savings plan |
|
| properties.displayName |
string |
Friendly name of the reservation |
|
| properties.instanceFlexibility |
Allows reservation discount to be applied across skus within the same auto fit group. Not all skus support instance size flexibility. |
||
| properties.quantity |
integer (int32) |
Quantity of the skus that are part of the reservation. Must be greater than zero. |
|
| properties.renew |
boolean |
False |
Setting this to true will automatically purchase a new benefit on the expiration date time. |
| properties.reservedResourceProperties.instanceFlexibility |
Turning this on will apply the reservation discount to other VMs in the same VM size group. Only specify for VirtualMachines reserved resource type. |
||
| properties.reservedResourceType |
string |
The reserved source type of the reservation, e.g. virtual machine. |
|
| properties.reviewDateTime |
string (date-time) |
This is the date-time when the Azure hybrid benefit needs to be reviewed. |
|
| properties.term |
string |
The term of the reservation, e.g. P1Y |
|
| sku |
The name of sku |
ReservationSkuProperty
The property of reservation sku object.
| Name | Type | Description |
|---|---|---|
| name |
string |
The name of the reservation sku. |
ReservationsListResult
The list of reservations and summary of roll out count of reservations in each state.
| Name | Type | Description |
|---|---|---|
| nextLink |
string (uri) |
The link (url) to the next page of results. |
| summary |
The roll out count summary of the reservations |
|
| value |
The list of reservations. |
ReservationSplitProperties
Properties of reservation split
| Name | Type | Description |
|---|---|---|
| splitDestinations |
string[] |
List of destination resource id that are created due to split. Format of the resource id is /providers/Microsoft.Capacity/reservationOrders/{reservationOrderId}/reservations/{reservationId} |
| splitSource |
string |
Resource id of the reservation from which this is split. Format of the resource id is /providers/Microsoft.Capacity/reservationOrders/{reservationOrderId}/reservations/{reservationId} |
ReservationStatusCode
The status of the reservation.
| Value | Description |
|---|---|
| None |
None |
| Pending |
Pending |
| Processing |
Processing |
| Active |
Active |
| PurchaseError |
PurchaseError |
| PaymentInstrumentError |
PaymentInstrumentError |
| Split |
Split |
| Merged |
Merged |
| Expired |
Expired |
| Succeeded |
Succeeded |
| CapacityError |
CapacityError |
| CapacityRestricted |
CapacityRestricted |
| Exchanged |
Exchanged |
| UnknownError |
UnknownError |
| RiskCheckFailed |
RiskCheckFailed |
| CreditLineCheckFailed |
CreditLineCheckFailed |
| Warning |
Warning |
| NoBenefitDueToSubscriptionTransfer |
NoBenefitDueToSubscriptionTransfer |
| NoBenefitDueToSubscriptionDeletion |
NoBenefitDueToSubscriptionDeletion |
| NoBenefit |
NoBenefit |
ReservationSummary
The roll up count summary of reservations in each state
| Name | Type | Description |
|---|---|---|
| cancelledCount |
number (float) |
The number of reservation in Cancelled state |
| expiredCount |
number (float) |
The number of reservation in Expired state |
| expiringCount |
number (float) |
The number of reservation in Expiring state |
| failedCount |
number (float) |
The number of reservation in Failed state |
| noBenefitCount |
number (float) |
The number of reservation in 'No Benefit' state |
| pendingCount |
number (float) |
The number of reservation in Pending state |
| processingCount |
number (float) |
The number of reservation in Processing state |
| succeededCount |
number (float) |
The number of reservation in Succeeded state |
| warningCount |
number (float) |
The number of reservation in Warning state |
ReservationSwapProperties
Properties of reservation swap
| Name | Type | Description |
|---|---|---|
| swapDestination |
string |
Reservation resource id that the original resource gets swapped to. Format of the resource id is /providers/microsoft.capacity/reservationOrders/{reservationOrderId}/reservations/{reservationId} |
| swapSource |
string |
Resource id of the source reservation that gets swapped. Format of the resource id is /providers/microsoft.capacity/reservationOrders/{reservationOrderId}/reservations/{reservationId} |
ReservationUtilizationAggregates
The aggregate values of reservation utilization
| Name | Type | Description |
|---|---|---|
| grain |
number (float) |
The grain of the aggregate |
| grainUnit |
string |
The grain unit of the aggregate |
| value |
number (float) |
The aggregate value |
| valueUnit |
string |
The aggregate value unit |
SkuName
The name of sku
| Name | Type | Description |
|---|---|---|
| name |
string |
systemData
Metadata pertaining to creation and last modification of the resource.
| Name | Type | Description |
|---|---|---|
| createdAt |
string (date-time) |
The timestamp of resource creation (UTC). |
| createdBy |
string |
The identity that created the resource. |
| createdByType |
The type of identity that created the resource. |
|
| lastModifiedAt |
string (date-time) |
The timestamp of resource last modification (UTC) |
| lastModifiedBy |
string |
The identity that last modified the resource. |
| lastModifiedByType |
The type of identity that last modified the resource. |