Reservation Order - Purchase

Purchase ReservationOrder and create resource under the specified URI.

PUT https://management.azure.com/providers/Microsoft.Capacity/reservationOrders/{reservationOrderId}?api-version=2022-11-01

URI Parameters

Name In Required Type Description
reservationOrderId
path True

string

Order Id of the reservation

api-version
query True

string

Supported version.

Request Body

Name Type Description
location

string

The Azure region where the reserved resource lives.

properties.appliedScopeProperties

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

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. This property will be deprecated and replaced by appliedScopeProperties instead for Single AppliedScopeType.

properties.billingPlan

ReservationBillingPlan

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.quantity

integer

Quantity of the skus that are part of the reservation.

properties.renew

boolean

Setting this to true will automatically purchase a new reservation on the expiration date time.

properties.reservedResourceProperties

ReservedResourceProperties

Properties specific to each reserved resource type. Not required if not applicable.

properties.reservedResourceType

ReservedResourceType

The type of the resource that is being reserved.

properties.reviewDateTime

string

This is the date-time when the Azure hybrid benefit needs to be reviewed.

properties.term

ReservationTerm

Represent the term of reservation.

sku

SkuName

The name of sku

Responses

Name Type Description
200 OK

ReservationOrderResponse

The resource has been created

202 Accepted

ReservationOrderResponse

The request is accepted and is being processed. Operation result link is in location header.

Headers

  • Location: string
  • Retry-After: integer
Other Status Codes

Error

Unexpected error

Examples

Purchase

Sample request

PUT https://management.azure.com/providers/Microsoft.Capacity/reservationOrders/a075419f-44cc-497f-b68a-14ee811d48b9?api-version=2022-11-01

{
  "sku": {
    "name": "standard_D1"
  },
  "location": "westus",
  "properties": {
    "reservedResourceType": "VirtualMachines",
    "billingScopeId": "/subscriptions/ed3a1871-612d-abcd-a849-c2542a68be83",
    "term": "P1Y",
    "billingPlan": "Monthly",
    "quantity": 1,
    "displayName": "TestReservationOrder",
    "appliedScopes": null,
    "appliedScopeType": "Shared",
    "reservedResourceProperties": {
      "instanceFlexibility": "On"
    },
    "renew": false
  }
}

Sample response

{
  "id": "/providers/microsoft.capacity/reservationOrders/1f14354c-dc12-4c8d-8090-6f295a3a34aa",
  "type": "Microsoft.Capacity/reservationOrders",
  "name": "1f14354c-dc12-4c8d-8090-6f295a3a34aa",
  "etag": 7,
  "properties": {
    "displayName": "cabri",
    "requestDateTime": "2017-08-30T03:49:19.0252126Z",
    "createdDateTime": "2017-08-30T03:51:49.8083758Z",
    "expiryDate": "2018-08-30",
    "expiryDateTime": "2018-08-30T03:51:49.8083758Z",
    "term": "P1Y",
    "billingPlan": "Monthly",
    "provisioningState": "Succeeded",
    "reservations": [
      {
        "id": "/providers/microsoft.capacity/reservationOrders/1f14354c-dc12-4c8d-8090-6f295a3a34aa/reservations/c8c926bd-fc5d-4e29-9d43-b68340ac23a6"
      }
    ],
    "originalQuantity": 7
  }
}
Location: https://management.azure.com/providers/microsoft.capacity/reservationOrders/1f14354c-dc12-4c8d-8090-6f295a3a34aa?api-version=2022-11-01
Retry-After: 120
{
  "id": "/providers/microsoft.capacity/reservationOrders/1f14354c-dc12-4c8d-8090-6f295a3a34aa",
  "type": "Microsoft.Capacity/reservationOrders",
  "name": "1f14354c-dc12-4c8d-8090-6f295a3a34aa",
  "etag": 7,
  "properties": {
    "displayName": "cabri",
    "billingPlan": "Monthly",
    "requestDateTime": "2017-08-30T03:49:19.0252126Z",
    "createdDateTime": "2017-08-30T03:51:49.8083758Z",
    "expiryDate": "2018-08-30",
    "expiryDateTime": "2018-08-30T03:51:49.8083758Z",
    "term": "P1Y",
    "provisioningState": "Succeeded",
    "reservations": [
      {
        "id": "/providers/microsoft.capacity/reservationOrders/1f14354c-dc12-4c8d-8090-6f295a3a34aa/reservations/c8c926bd-fc5d-4e29-9d43-b68340ac23a6"
      }
    ],
    "originalQuantity": 7
  }
}

Definitions

Name Description
AppliedScopeProperties

Properties specific to applied scope type. Not required if not applicable. Required and need to provide tenantId and managementGroupId if AppliedScopeType is ManagementGroup

AppliedScopeType

Type of the Applied Scope.

BillingCurrencyTotal

Currency and amount that customer will be charged in customer's local currency for renewal purchase. Tax is not included.

createdByType

The type of identity that created the resource.

Error

Error information

ErrorResponseCode

Error code describing the reason that service is not able to process the incoming request

ExtendedErrorInfo

Extended error information including error code and error message

ExtendedStatusInfo
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.

Kind

Resource Provider type to be reserved.

PaymentDetail

Information about payment related to a reservation order.

PaymentStatus

Describes whether the payment is completed, failed, cancelled or scheduled in the future.

Price

Pricing information containing the amount and the currency code

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.

ProvisioningState

Represent the current state of the Reservation.

PurchaseRequest

The request for reservation purchase

RenewPropertiesResponse

The renew properties for a reservation.

ReservationBillingPlan

Represent the billing plans.

ReservationMergeProperties

Properties of reservation merge

ReservationOrderBillingPlanInformation

Information describing the type of billing plan for this reservation.

ReservationOrderResponse

Details of a reservation order being returned.

ReservationResponse

The definition of the reservation.

ReservationSplitProperties

Properties of reservation split

ReservationsProperties

The properties of the reservations

ReservationStatusCode
ReservationSwapProperties

Properties of reservation swap

ReservationTerm

Represent the term of reservation.

ReservationUtilizationAggregates

The aggregate values of reservation utilization

ReservedResourceProperties

Properties specific to each reserved resource type. Not required if not applicable.

ReservedResourceType

The type of the resource that is being reserved.

SkuName

The name of sku

systemData

Metadata pertaining to creation and last modification of the resource.

Utilization

Reservation utilization

AppliedScopeProperties

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 savings plan should apply benefit.

AppliedScopeType

Type of the Applied Scope.

Name Type Description
ManagementGroup

string

Shared

string

Single

string

BillingCurrencyTotal

Currency and amount that customer will be charged in customer's local currency for renewal purchase. Tax is not included.

Name Type Description
amount

number

currencyCode

string

The ISO 4217 3-letter currency code for the currency used by this purchase record.

createdByType

The type of identity that created the resource.

Name Type Description
Application

string

Key

string

ManagedIdentity

string

User

string

Error

Error information

Name Type Description
error

ExtendedErrorInfo

Extended error information including error code and error message

ErrorResponseCode

Error code describing the reason that service is not able to process the incoming request

Name Type Description
ActivateQuoteFailed

string

AppliedScopesNotAssociatedWithCommerceAccount

string

AppliedScopesSameAsExisting

string

AuthorizationFailed

string

BadRequest

string

BillingCustomerInputError

string

BillingError

string

BillingPaymentInstrumentHardError

string

BillingPaymentInstrumentSoftError

string

BillingScopeIdCannotBeChanged

string

BillingTransientError

string

CalculatePriceFailed

string

CapacityUpdateScopesFailed

string

ClientCertificateThumbprintNotSet

string

CreateQuoteFailed

string

Forbidden

string

FulfillmentConfigurationError

string

FulfillmentError

string

FulfillmentOutOfStockError

string

FulfillmentTransientError

string

HttpMethodNotSupported

string

InternalServerError

string

InvalidAccessToken

string

InvalidFulfillmentRequestParameters

string

InvalidHealthCheckType

string

InvalidLocationId

string

InvalidRefundQuantity

string

InvalidRequestContent

string

InvalidRequestUri

string

InvalidReservationId

string

InvalidReservationOrderId

string

InvalidSingleAppliedScopesCount

string

InvalidSubscriptionId

string

InvalidTenantId

string

MissingAppliedScopesForSingle

string

MissingTenantId

string

NoValidReservationsToReRate

string

NonsupportedAccountId

string

NotSpecified

string

NotSupportedCountry

string

OperationCannotBePerformedInCurrentState

string

OperationFailed

string

PatchValuesSameAsExisting

string

PaymentInstrumentNotFound

string

PurchaseError

string

ReRateOnlyAllowedForEA

string

RefundLimitExceeded

string

ReservationIdNotInReservationOrder

string

ReservationOrderCreationFailed

string

ReservationOrderIdAlreadyExists

string

ReservationOrderNotEnabled

string

ReservationOrderNotFound

string

RiskCheckFailed

string

RoleAssignmentCreationFailed

string

SelfServiceRefundNotSupported

string

ServerTimeout

string

UnauthenticatedRequestsThrottled

string

UnsupportedReservationTerm

string

ExtendedErrorInfo

Extended error information including error code and error message

Name Type Description
code

ErrorResponseCode

Error code describing the reason that service is not able to process the incoming request

message

string

ExtendedStatusInfo

Name Type Description
message

string

The message giving detailed information about the status code.

statusCode

ReservationStatusCode

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.

Name Type Description
Off

string

On

string

Kind

Resource Provider type to be reserved.

Name Type Description
Microsoft.Compute

string

PaymentDetail

Information about payment related to a reservation order.

Name Type Description
billingAccount

string

Shows the Account that is charged for this payment.

billingCurrencyTotal

Price

Amount charged in Billing currency. Tax not included. Is null for future payments

dueDate

string

Date when the payment needs to be done.

extendedStatusInfo

ExtendedStatusInfo

paymentDate

string

Date when the transaction is completed. Is null when it is scheduled.

pricingCurrencyTotal

Price

Amount in pricing currency. Tax not included.

status

PaymentStatus

Describes whether the payment is completed, failed, cancelled or scheduled in the future.

PaymentStatus

Describes whether the payment is completed, failed, cancelled or scheduled in the future.

Name Type Description
Cancelled

string

Failed

string

Scheduled

string

Succeeded

string

Price

Pricing information containing the amount and the currency code

Name Type Description
amount

number

currencyCode

string

The ISO 4217 3-letter currency code for the currency used by this purchase record.

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.

Name Type Description
amount

number

currencyCode

string

The ISO 4217 3-letter currency code for the currency used by this purchase record.

ProvisioningState

Represent the current state of the Reservation.

Name Type Description
BillingFailed

string

Cancelled

string

ConfirmedBilling

string

ConfirmedResourceHold

string

Created

string

Creating

string

Expired

string

Failed

string

Merged

string

PendingBilling

string

PendingResourceHold

string

Split

string

Succeeded

string

PurchaseRequest

The request for reservation purchase

Name Type Default value Description
location

string

The Azure region where the reserved resource lives.

properties.appliedScopeProperties

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

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. This property will be deprecated and replaced by appliedScopeProperties instead for Single AppliedScopeType.

properties.billingPlan

ReservationBillingPlan

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.quantity

integer

Quantity of the skus that are part of the reservation.

properties.renew

boolean

False

Setting this to true will automatically purchase a new reservation on the expiration date time.

properties.reservedResourceProperties

ReservedResourceProperties

Properties specific to each reserved resource type. Not required if not applicable.

properties.reservedResourceType

ReservedResourceType

The type of the resource that is being reserved.

properties.reviewDateTime

string

This is the date-time when the Azure hybrid benefit needs to be reviewed.

properties.term

ReservationTerm

Represent the term of reservation.

sku

SkuName

The name of sku

RenewPropertiesResponse

The renew properties for a reservation.

Name Type Description
billingCurrencyTotal

BillingCurrencyTotal

Currency and amount that customer will be charged in customer's local currency for renewal purchase. Tax is not included.

pricingCurrencyTotal

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

PurchaseRequest

The request for reservation purchase

ReservationBillingPlan

Represent the billing plans.

Name Type Description
Monthly

string

Upfront

string

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}

ReservationOrderBillingPlanInformation

Information describing the type of billing plan for this reservation.

Name Type Description
nextPaymentDueDate

string

For recurring billing plans, indicates the date when next payment will be processed. Null when total is paid off.

pricingCurrencyTotal

Price

Amount of money to be paid for the Order. Tax is not included.

startDate

string

Date when the billing plan has started.

transactions

PaymentDetail[]

Information about payment related to a reservation order.

ReservationOrderResponse

Details of a reservation order being returned.

Name Type Description
etag

integer

id

string

Identifier of the reservation

name

string

Name of the reservation

properties.benefitStartTime

string

This is the DateTime when the reservation benefit started.

properties.billingPlan

ReservationBillingPlan

Represent the billing plans.

properties.createdDateTime

string

This is the DateTime when the reservation was created.

properties.displayName

string

Friendly name for user to easily identified the reservation.

properties.expiryDate

string

This is the date when the reservation will expire.

properties.expiryDateTime

string

This is the date-time when the reservation will expire.

properties.originalQuantity

integer

Total Quantity of the skus purchased in the reservation.

properties.planInformation

ReservationOrderBillingPlanInformation

Information describing the type of billing plan for this reservation.

properties.provisioningState

ProvisioningState

Current state of the reservation.

properties.requestDateTime

string

This is the DateTime when the reservation was initially requested for purchase.

properties.reservations

ReservationResponse[]

The definition of the reservation.

properties.reviewDateTime

string

This is the date-time when the Azure Hybrid Benefit needs to be reviewed.

properties.term

ReservationTerm

Represent the term of reservation.

systemData

systemData

Metadata pertaining to creation and last modification of the resource.

type

string

Type of resource. "Microsoft.Capacity/reservations"

ReservationResponse

The definition of the reservation.

Name Type Description
etag

integer

id

string

Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"

kind

Kind

Resource Provider type to be reserved.

location

string

The Azure region where the reserved resource lives.

name

string

The name of the resource

properties

ReservationsProperties

The properties associated to this reservation

sku

SkuName

The sku information associated to this reservation

systemData

systemData

Azure Resource Manager metadata containing createdBy and modifiedBy information.

type

string

The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

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}

ReservationsProperties

The properties of the reservations

Name Type Default value Description
appliedScopeProperties

AppliedScopeProperties

Properties specific to applied scope type. Not required if not applicable. Required and need to provide tenantId and managementGroupId if AppliedScopeType is ManagementGroup

appliedScopeType

AppliedScopeType

The applied scope type

appliedScopes

string[]

The list of applied scopes

archived

boolean

Indicates if the reservation is archived

benefitStartTime

string

This is the DateTime when the reservation benefit started.

billingPlan

ReservationBillingPlan

The billing plan options available for this sku.

billingScopeId

string

Subscription that will be charged for purchasing reservation or savings plan

capabilities

string

Capabilities of the reservation

displayName

string

Friendly name for user to easily identify the reservation

displayProvisioningState

string

The provisioning state of the reservation for display, e.g. Succeeded

effectiveDateTime

string

DateTime of the reservation starting when this version is effective from.

expiryDate

string

This is the date when the reservation will expire.

expiryDateTime

string

This is the date-time when the reservation will expire.

extendedStatusInfo

ExtendedStatusInfo

The message giving detailed information about the status code.

instanceFlexibility

InstanceFlexibility

Allows reservation discount to be applied across skus within the same auto fit group. Not all skus support instance size flexibility.

lastUpdatedDateTime

string

DateTime of the last time the reservation was updated.

mergeProperties

ReservationMergeProperties

Properties of reservation merge

provisioningState

ProvisioningState

Current state of the reservation.

provisioningSubState

string

The provisioning sub-state of the reservation, e.g. Succeeded

purchaseDate

string

This is the date when the reservation was purchased.

purchaseDateTime

string

This is the date-time when the reservation was purchased.

quantity

integer

Quantity of the skus that are part of the reservation.

renew

boolean

False

Setting this to true will automatically purchase a new reservation on the expiration date time.

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}.

renewProperties

RenewPropertiesResponse

The renew properties for a reservation.

renewSource

string

Reservation Id of the reservation from which this reservation is renewed. Format of the resource Id is /providers/Microsoft.Capacity/reservationOrders/{reservationOrderId}/reservations/{reservationId}.

reservedResourceType

ReservedResourceType

The type of the resource that is being reserved.

reviewDateTime

string

This is the date-time when the Azure Hybrid Benefit needs to be reviewed.

skuDescription

string

Description of the sku in english.

splitProperties

ReservationSplitProperties

Properties of reservation split

swapProperties

ReservationSwapProperties

Properties of reservation swap

term

ReservationTerm

Represent the term of reservation.

userFriendlyAppliedScopeType

string

The applied scope type of the reservation for display, e.g. Shared

userFriendlyRenewState

string

The renew state of the reservation for display, e.g. On

utilization

Utilization

Reservation utilization

ReservationStatusCode

Name Type Description
Active

string

Expired

string

Merged

string

None

string

PaymentInstrumentError

string

Pending

string

Processing

string

PurchaseError

string

Split

string

Succeeded

string

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}

ReservationTerm

Represent the term of reservation.

Name Type Description
P1Y

string

P3Y

string

P5Y

string

ReservationUtilizationAggregates

The aggregate values of reservation utilization

Name Type Description
grain

number

The grain of the aggregate

grainUnit

string

The grain unit of the aggregate

value

number

The aggregate value

valueUnit

string

The aggregate value unit

ReservedResourceProperties

Properties specific to each reserved resource type. Not required if not applicable.

Name Type Description
instanceFlexibility

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.

ReservedResourceType

The type of the resource that is being reserved.

Name Type Description
AVS

string

AppService

string

AzureDataExplorer

string

AzureFiles

string

BlockBlob

string

CosmosDb

string

DataFactory

string

Databricks

string

DedicatedHost

string

ManagedDisk

string

MariaDb

string

MySql

string

NetAppStorage

string

PostgreSql

string

RedHat

string

RedHatOsa

string

RedisCache

string

SapHana

string

SqlAzureHybridBenefit

string

SqlDataWarehouse

string

SqlDatabases

string

SqlEdge

string

SuseLinux

string

VMwareCloudSimple

string

VirtualMachineSoftware

string

VirtualMachines

string

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

The timestamp of resource creation (UTC).

createdBy

string

The identity that created the resource.

createdByType

createdByType

The type of identity that created the resource.

lastModifiedAt

string

The timestamp of resource last modification (UTC)

lastModifiedBy

string

The identity that last modified the resource.

lastModifiedByType

createdByType

The type of identity that last modified the resource.

Utilization

Reservation utilization

Name Type Description
aggregates

ReservationUtilizationAggregates[]

The array of aggregates of a reservation's utilization

trend

string

last 7 day utilization trend for a reservation