Azure Consumption

The Azure Consumption APIs give you programmatic access to cost and usage data for your Azure resources. The APIs currently only support Enterprise Enrollments, Web Direct subscriptions (with a few exceptions), and CSP Azure plan subscriptions. The APIs are continually updated to support other types of Azure subscriptions.

Azure Consumption APIs provide access to:

Enterprise Customers Only
- Price sheet
- Budgets
- Forecasts
- Balances
- Tags
- Cost Tags
Enterprise and Web Direct Customers
- Reservation Details
- Reservation Summaries
- Marketplace Charges
- Usage Details
- Reservation Recommendations

List of Unsupported Subscription Types

MS-AZR-0145P (CSP)
MS-AZR-0146P (CSP)
MS-AZR-159P (CSP)
MS-AZR-0036P (sponsored)
MS-AZR-0143P (sponsored)
MS-AZR-0015P (internal)
MS-AZR-0144P (DreamSpark)

Working with billing periods and date ranges

Usage Details and Marketplace Charges accept billing period or date ranges for defining the start and end dates for the usage data.

Here's the API behavior based on billing periods and date ranges in request:

Billing period in request	Start date in request	End date in request	API behavior
no	no	no	Data for current billing period is returned in response
no	yes	no	Data for current billing period is returned in response
no	no	yes	Data for current billing period is returned in response
no	yes	yes	Data for specified Start and End Date is returned in response
yes	no	no	Data for specified billing period is returned in response
yes	yes	no	Data for specified billing period is returned in response
yes	no	yes	Data for specified billing period is returned in response
yes	yes	yes	Data for specified Start and End Date is returned in response, supplied billing period is ignored

Maximum allowed date range is 12 months in one request and data is available from May 1, 2014 or later.

Getting list of billing periods

To providie a valid billing period in a request, the client should first get a list of the available billing periods by subscription by using the following API

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Billing/billingPeriods?api-version=2017-04-24-preview

Using the list, the client can pick a specific billing period to get consumption data.

Late Arriving Data

To accommodate third party services that have delays in reporting usage, the reported usage date is set to the time at which the usage data was sent, as opposed to when the actual usage took place that is, consumption time.

As a result, the usage is rated for and applied to the reported time. In order to represent the actual consumption time, the properties.AdditionalProperties field will now contain two other properties. ConsumptionBeginTime and ConsumptionEndTime are the new fields that correspond to the actual consumption time window.

These changes result in a few scenarios that need to be addressed when calling the usage details API:

Month End Reporting: For usage that occurred during a month, but reported during the next month, customers need to look at the additionalProperties field to assign the usage, to the appropriate month.
Query Usage details: When you query the usage details API by a date range, the query only applies to usage report date and not the consumption time in the additionalProperties field. For customers looking to map usage details to invoices, this update does not affect the process as the invoice processes the usage based on the usage report date. For customers, looking to map usage details to a specific calendar date/month, this update is a breaking change and for these scenarios the usage report date can't be used and the date that the usage occurred, in the additionalProperties section must be used.

Sample Call for More Details:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Consumption/usageDetails?api-version=2018-03-31&$expand=properties/additionalProperties

Sample Response snippet:

  "properties": {
    "billingPeriodId":"/subscriptions/{subscriptionid}/providers/Microsoft.Billing/billingPeriods/20180501",
    "usageStart":"2018-05-01T00:00:00.0000000Z",
    "usageEnd":"2018-05-01T23:59:59.0000000Z",
    "instanceId":"/subscriptions/{subscriptionid}/resourceGroups/{resourcegroup}/providers/Microsoft.Cdn/profiles/{profile}",
    "instanceName":"{id}",
    "instanceLocation":"SouthCentralUS",
    "meterId":"6b88ada0-cbc0-4874-be0e-23004f8b4de7",
    "usageQuantity":0.002065,
    "pretaxCost":0,
    "currency":"USD",
    "additionalProperties": {
      "Provider": "1",
      "ConsumptionBeginTime": "2018-05-01T19:00:00",
      "ConsumptionEndTime": "2018-05-01T20:00:00"
    }
  }

Share via

Azure Consumption

List of Unsupported Subscription Types

Working with billing periods and date ranges

Getting list of billing periods

Late Arriving Data

See also

Additional resources