APIs for Azure reservation automation

Article
11/17/2023

Use Azure APIs to programmatically get information for your organization about Azure service or software reservations.

Find reservation plans to buy

Use the Reservation recommendation API to get recommendations on which reservations plan to buy based on your organization's usage. For more information, see Reservation Recommendations.

You can also analyze your resource usage by using the Consumption API Usage Detail. For more information, see Usage Details - List For Billing Period By Billing Account. The Azure resources that you use consistently are usually the best candidate for a reservation.

Buy a reservation

You can purchase Azure reservations and software plans programmatically by using REST APIs. To learn more, see Reservation Order - Purchase API.

Here's a sample request to purchase by using the REST API:

PUT https://management.azure.com/providers/Microsoft.Capacity/reservationOrders/<GUID>?api-version=2019-04-01

Request body:

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

You can also buy a reservation in the Azure portal. For more information, see the following articles:

Service plans:

Software plans:

SUSE Linux software

Get reservations

If you're an Azure customer with an Enterprise Agreement (EA customer), you can get the reservations your organization bought by using the Reservation Transactions - List. For other subscriptions, get the list of reservations you bought and have permissions to view by using the API Reservation Order - List. By default, the account owner or person that bought the reservation has permissions to view the reservation.

See reservation usage

If you're an EA customer, you can programmatically view how the reservations in your organization are being used. For more information, see Reservation Transactions - List. For other subscriptions, use the API Reservations Summaries - List By Reservation Order And Reservation.

If you find that your organization's reservations are being under-used:

Make sure the virtual machines that your organization creates match the VM size that's on the reservation.
Make sure instance size flexibility is on. For more information, see Manage reservations - Change optimize setting for Reserved VM Instances.
Change the scope of reservation to shared so that it applies more broadly. For more information, see Manage reservations - Change the scope for a reservation.
Exchange the unused quantity. For more information, see Manage reservations.

Give access to reservations

Get the list of all reservations that a user has access to by using the Reservation - Operation - List API. To give access to a reservation programmatically, see one of the following articles:

Split or merge reservation

After you buy more than one resource instance within a reservation, you may want to assign instances within that reservation to different subscriptions. You can change the reservation scope so that it applies to all subscriptions within the same billing context. But for cost management or budgeting purposes, you may want to keep the scope as "single subscription" and assign reservation instances to a specific subscription.

To split a reservation, use the API Reservation - Split. You can also split a reservation by using PowerShell. For more information, see Manage reservations - Split reservation into two reservations.

To merge two reservations into one reservation, use the API Reservation - Merge.

Change scope for a reservation

The scope of a reservation can be single subscription, single resource group or all subscriptions in your billing context. If you set the scope to single subscription or single resource group, the reservation is matched to running resources in the selected subscription. If you delete or move the subscription or the resource group, the reservation will not be utilized. If you set the scope to shared, Azure matches the reservation to resources that run in all the subscriptions within the billing context. The billing context is dependent on the subscription you used to buy the reservation. You can select the scope at purchase or change it anytime after purchase. For more information, see Manage Reservations - Change the scope.

To change the scope programmatically, use the API Reservation - Update.