Skip to content

Commit b882f22

Browse files
author
Maddie Minnick
committed
updated docs to use Cost Details API
1 parent 53ec1b4 commit b882f22

File tree

2 files changed

+239
-176
lines changed

2 files changed

+239
-176
lines changed

‎articles/cost-management-billing/manage/review-enterprise-billing.md

Lines changed: 97 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -1,182 +1,149 @@
11
---
22
title: Review Azure enterprise enrollment billing data with REST API
3-
description: Learn how to use Azure REST APIs to review enterprise enrollment billing information.
4-
author: racheg
5-
ms.reviewer: racheg
3+
description: Learn how to use the Cost Details API to review enterprise enrollment billing information. You can use this asynchronous API to get detailed cost and usage data.
4+
author: maddieminn
5+
ms.reviewer: maminn
66
ms.service: cost-management-billing
7-
ms.subservice: enterprise
7+
ms.subservice: cost-management
88
ms.topic: article
9-
ms.date: 04/08/2025
10-
ms.author: racheg
9+
ms.date: 07/28/2025
10+
ms.author: maminn
1111
---
1212

1313
# Review enterprise enrollment billing using REST APIs
1414

15-
Azure Reporting APIs help you review and manage your Azure costs.
15+
Cost Management APIs help you review and manage your Azure costs.
1616

17-
In this article, you learn to retrieve the billing information associated with billing accounts, department, or enterprise agreement (EA) enrollment accounts using the Azure REST APIs.
17+
The Cost Details API, in particular, helps you review and manage your Azure costs by providing detailed, unaggregated cost data.
1818

19-
## Individual account billing
19+
This asynchronous API allows you to generate and download cost reports for your Enterprise Agreement (EA) billing accounts, departments, or enrollment accounts.
2020

21-
To get usage details for accounts in a department:
21+
In this article, you learn to retrieve the billing information associated with EA billing accounts, departments, or enrollment accounts using the Cost Details API.
2222

23-
```http
24-
GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/providers/Microsoft.Consumption/usageDetails?api-version=2018-06-30
25-
Content-Type: application/json
26-
Authorization: Bearer
27-
```
23+
> [!IMPORTANT]
24+
> The Cost Details API is asynchronous and report-based. You submit a request to generate a report, poll for its completion, and then download the resulting file from a secure URL.
2825
29-
The `{billingAccountId}` parameter is required and should contain the ID for the account.
26+
## How the Cost Details API works
3027

31-
The following headers are required:
28+
The Cost Details API uses an asynchronous workflow:
29+
30+
1. **Create a report**: Submit a POST request to generate a cost details report for your EA scope
31+
2. **Poll for status**: Check the operation status until the report is complete
32+
3. **Download the report**: Use the provided download URL to get the CSV file with your cost data
33+
34+
> [!NOTE]
35+
> The API supports both **ActualCost** and **AmortizedCost** metrics. ActualCost shows charges as they were billed, while AmortizedCost spreads reservation and savings plans purchases across their term and reallocates costs to the resources that used the reservation or savings plan. For example, a $365 reservation purchase appears as $1.00 daily charges in amortized cost view.
3236
33-
|Request header|Description|
34-
|--------------------|-----------------|
35-
|*Content-Type:*|Required. Set to `application/json`.|
36-
|*Authorization:*|Required. Set to a valid `Bearer` API key. |
37+
## Working with different EA scopes
3738

38-
This example shows a synchronous call that returns details for the current billing cycle. For performance reasons, synchronous calls return information for the last month. You can also call the API asynchronously to return data for 36 months.
39+
The Cost Details API supports three EA scopes, each providing different levels of cost aggregation:
3940

41+
- **Billing account scope**: Cost details for the entire EA billing account
42+
- **Department scope**: Cost details aggregated for all accounts in a specific department
43+
- **Enrollment account scope**: Cost details for a specific enrollment account
4044

41-
## Response
45+
## Step 1: Create a cost details report
4246

43-
Status code 200 (OK) is returned for a successful response, which contains a list of detailed costs for the account.
47+
Submit a POST request to generate a cost details report:
48+
49+
```http
50+
POST https://management.azure.com/providers/Microsoft.Billing/{scope}/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2025-03-01
51+
Content-Type: application/json
52+
Authorization: Bearer {access-token}
4453
45-
```json
4654
{
47-
"value": [
48-
{
49-
"id": "/providers/Microsoft.Billing/BillingAccounts/1234/providers/Microsoft.Billing/billingPeriods/201702/providers/Microsoft.Consumption/usageDetails/usageDetailsId1",
50-
"name": "usageDetailsId1",
51-
"type": "Microsoft.Consumption/usageDetails",
52-
"properties": {
53-
...
54-
"usageStart": "2017-02-13T00:00:00Z",
55-
"usageEnd": "2017-02-13T23:59:59Z",
56-
"instanceName": "shared1",
57-
"instanceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/Default-Web-eastasia/providers/Microsoft.Web/sites/shared1",
58-
"currency": "USD",
59-
"usageQuantity": 0.00328,
60-
"billableQuantity": 0.00328,
61-
"pretaxCost": 0.67,
62-
"isEstimated": false,
63-
...
64-
}
65-
}
66-
]
55+
"metric": "ActualCost",
56+
"timePeriod": {
57+
"start": "2025-07-01",
58+
"end": "2025-07-31"
59+
}
6760
}
68-
```
61+
```
6962

70-
This example is abbreviated; see [Get usage detail for a billing account](/rest/api/consumption/usagedetails/list#billingaccountusagedetailslist-legacy) for a complete description of each response field and error handling.
63+
Where `{scope}` varies based on your desired scope:
7164

72-
## Department billing
65+
- **Billing account scope**: `billingAccounts/{billingAccountId}`
66+
- **Department scope**: `departments/{departmentId}`
67+
- **Enrollment account scope**: `enrollmentAccounts/{enrollmentAccountId}`
7368

74-
Get usage details aggregated for all accounts in a department.
69+
## Step 2: Poll for report status
70+
71+
Check the operation status until the report is complete:
7572

7673
```http
77-
GET https://management.azure.com/providers/Microsoft.Billing/departments/{departmentId}/providers/Microsoft.Consumption/usageDetails?api-version=2018-06-30
78-
Content-Type: application/json
79-
Authorization: Bearer
74+
GET https://management.azure.com/providers/Microsoft.Billing/{scope}/providers/Microsoft.CostManagement/costDetailsOperationStatus/{operationId}?api-version=2025-03-01
75+
Authorization: Bearer {access-token}
8076
```
8177

82-
The `{departmentId}` parameter is required and should contain the ID for the department in the enrollment account.
78+
Where `{scope}` uses the same values as in Step 1:
8379

84-
The following headers are required:
80+
- **Billing account scope**: `billingAccounts/{billingAccountId}`
81+
- **Department scope**: `departments/{departmentId}`
82+
- **Enrollment account scope**: `enrollmentAccounts/{enrollmentAccountId}`
8583

86-
|Request header|Description|
87-
|--------------------|-----------------|
88-
|*Content-Type:*|Required. Set to `application/json`.|
89-
|*Authorization:*|Required. Set to a valid `Bearer` API key. |
84+
## Step 3: Download the report
9085

91-
This example shows a synchronous call that returns details for the current billing cycle. For performance reasons, synchronous calls return information for the last month. You can also call the API asynchronously to return data for 36 months.
86+
When the report status shows "Completed," the response includes a `blobLink` for downloading the CSV file containing the cost details for your selected scope.
9287

93-
### Response
88+
## Request parameters
9489

95-
Status code 200 (OK) is returned for a successful response, which contains a list of detailed usage information and costs for a given billing period and invoice ID for the department.
90+
The request body supports the following parameters:
9691

92+
- **metric** - The type of report requested. Can be either `ActualCost` or `AmortizedCost`. If not specified, defaults to `ActualCost`.
93+
- **timePeriod** - The requested date range for your data. Specify `start` and `end` dates in YYYY-MM-DD format. Can't be used alongside invoiceId or billingPeriod parameters.
94+
- **invoiceId** - The requested invoice for your data. This parameter is only used by Microsoft Customer Agreement customers and can only be used at the Billing Profile or Customer scope. Can't be used alongside billingPeriod or timePeriod parameters.
95+
- **billingPeriod** - The requested billing period for your data. This parameter is only used by Enterprise Agreement customers. Use the YearMonth format (for example, 202408). Can't be used alongside invoiceId or timePeriod parameters.
9796

98-
The following example shows the output of the REST API for department `1234`.
97+
> [!NOTE]
98+
> If none of the timePeriod, invoiceId, or billingPeriod parameters are provided in the request body, the API returns the current month's cost.
9999
100-
```json
101-
{
102-
"value": [
103-
{
104-
"id": "/providers/Microsoft.Billing/Departments/1234/providers/Microsoft.Billing/billingPeriods/201702/providers/Microsoft.Consumption/usageDetails/usageDetailsId1",
105-
"name": "usageDetailsId1",
106-
"type": "Microsoft.Consumption/usageDetails",
107-
"properties": {
108-
"billingPeriodId": "/providers/Microsoft.Billing/Departments/1234/providers/Microsoft.Billing/billingPeriods/201702",
109-
"invoiceId": "/providers/Microsoft.Billing/Departments/1234/providers/Microsoft.Billing/invoices/201703-123456789",
110-
"usageStart": "2017-02-13T00:00:00Z",
111-
"usageEnd": "2017-02-13T23:59:59Z",
112-
"instanceName": "shared1",
113-
"instanceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/Default-Web-eastasia/providers/Microsoft.Web/sites/shared1",
114-
"instanceLocation": "eastasia",
115-
"currency": "USD",
116-
"usageQuantity": 0.00328,
117-
"billableQuantity": 0.00328,
118-
"pretaxCost": 0.67,
119-
...
120-
}
121-
}
122-
]
123-
}
124-
```
100+
The following headers are required:
125101

126-
This example is abbreviated; see [Get usage detail for a department](/rest/api/consumption/usagedetails/list#departmentusagedetailslist-legacy) for a complete description of each response field and error handling.
102+
|Request header|Description|
103+
|--------------------|-----------------|
104+
|*Content-Type:*|Required. Set to `application/json`.|
105+
|*Authorization:*|Required. Set to a valid `Bearer` [access token](/rest/api/azure/#authorization-code-grant-interactive-clients). |
127106

128-
## Enrollment account billing
107+
## Response
129108

130-
Get usage details aggregated for the enrollment account.
109+
### Initial response (HTTP 202 Accepted)
131110

132-
```http
133-
GET https://management.azure.com/providers/Microsoft.Billing/enrollmentAccounts/{enrollmentAccountId}/providers/Microsoft.Consumption/usageDetails?api-version=2018-06-30
134-
Content-Type: application/json
135-
Authorization: Bearer
136-
```
111+
The initial POST request returns status code 202 (Accepted) with response headers:
137112

138-
The `{enrollmentAccountId}` parameter is required and should contain the ID for the enrollment account.
113+
| Name | Type | Description |
114+
| --- | --- | --- |
115+
| Location | String | URL to check the status of the asynchronous operation |
116+
| Retry-After | Integer | Expected time in seconds for the report to be generated |
139117

140-
The following headers are required:
118+
### Polling response (HTTP 200 OK)
141119

142-
|Request header|Description|
143-
|--------------------|-----------------|
144-
|*Content-Type:*|Required. Set to `application/json`.|
145-
|*Authorization:*|Required. Set to a valid `Bearer` API key. |
120+
When the report is complete, the polling endpoint returns status code 200 (OK) with the report details, including a `blobLink` for downloading the CSV file.
146121

147-
This example shows a synchronous call that returns details for the current billing cycle. For performance reasons, synchronous calls return information for the last month. You can also call the API asynchronously to return data for 36 months.
122+
## Cost details file fields
148123

149-
### Response
124+
The downloaded CSV file contains detailed cost and usage data with key fields including:
150125

151-
Status code 200 (OK) is returned for a successful response, which contains a list of detailed usage information and costs for a given billing period and invoice ID for the department.
126+
- **Date** - The usage or purchase date of the charge
127+
- **BillingAccountId** - Unique identifier for the EA billing account
128+
- **InvoiceSectionId** - Unique identifier for the EA department (if applicable)
129+
- **AccountId** - Unique identifier for the EA enrollment account
130+
- **SubscriptionId** - Unique identifier for the Azure subscription
131+
- **ResourceGroup** - Name of the resource group
132+
- **CostInBillingCurrency** - Cost of the charge in the billing currency before credits or taxes
133+
- **ChargeType** - Indicates whether the charge represents usage, a purchase, or a refund
134+
- **PricingModel** - Identifier that indicates how the meter is priced
152135

153-
The following example shows the output of the REST API for enterprise enrollment `1234`.
136+
For a complete list of all fields and their descriptions, see [Understand cost details fields](../automate/understand-usage-details-fields.md).
154137

155-
```json
156-
{
157-
"value": [
158-
{
159-
"id": "/providers/Microsoft.Billing/EnrollmentAccounts/1234/providers/Microsoft.Billing/billingPeriods/201702/providers/Microsoft.Consumption/usageDetails/usageDetailsId1",
160-
"name": "usageDetailsId1",
161-
"type": "Microsoft.Consumption/usageDetails",
162-
"properties": {
163-
"billingPeriodId": "/providers/Microsoft.Billing/EnrollmentAccounts/1234/providers/Microsoft.Billing/billingPeriods/201702",
164-
"invoiceId": "/providers/Microsoft.Billing/EnrollmentAccounts/1234/providers/Microsoft.Billing/invoices/201703-123456789",
165-
"usageStart": "2017-02-13T00:00:00Z",
166-
"usageEnd": "2017-02-13T23:59:59Z",
167-
....
168-
"currency": "USD",
169-
"usageQuantity": 0.00328,
170-
"billableQuantity": 0.00328,
171-
"pretaxCost": 0.67,
172-
...
173-
}
174-
}
175-
]
176-
}
177-
```
138+
## Best practices
178139

179-
This example is abbreviated; see [Get usage detail for an enrollment account](/rest/api/consumption/usagedetails/list#enrollmentaccountusagedetailslist-legacy) for a complete description of each response field and error handling.
140+
- **Request frequency**: Generate reports at most once per day for a given scope and date range. Cost data is refreshed every four hours.
141+
- **Date range**: For large datasets, limit the date range (for example, generate daily or weekly reports) to keep file sizes manageable.
142+
- **Data retention**: Download and store reports promptly. The download URL expires after a short period (typically one hour).
180143

181144
## Next steps
182-
- [Get started with Azure REST API](/rest/api/azure/)
145+
146+
- [Get started with Azure REST API](/rest/api/azure/)
147+
- [Learn more about the Cost Details API](/rest/api/cost-management/generate-cost-details-report)
148+
- [Get small cost datasets on demand](../automate/get-small-usage-datasets-on-demand.md)
149+
- [Understand cost details fields](../automate/understand-usage-details-fields.md)

0 commit comments

Comments
 (0)