Skip to content

Commit 85f166e

Browse files
denreadenrea
authored
Merge pull request #303551 from maddieminn/maminn/review-costs-freshness
Updated Billing Rest API Example Docs to use Cost Details API
2 parents d827f7c + 746667c commit 85f166e

File tree

2 files changed

+256
-176
lines changed

2 files changed

+256
-176
lines changed

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

Lines changed: 111 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -1,182 +1,163 @@
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+
> [!TIP]
24+
> This REST API is ideal for automation scenarios where you need to programmatically retrieve cost data on a regular basis. You can integrate it into scripts, applications, or automated workflows to pull cost reports for analysis, budgeting, or compliance reporting.
2825
29-
The `{billingAccountId}` parameter is required and should contain the ID for the account.
26+
> [!IMPORTANT]
27+
> The Cost Details API is asynchronous and report-based. You submit a request to generate a downloadable file (report), poll for its completion, and then download the resulting file from a secure URL.
3028
31-
The following headers are required:
29+
## How the Cost Details API works
30+
31+
The Cost Details API uses an asynchronous workflow:
32+
33+
1. **Create a report**: Submit a POST request to generate a Cost Details report for your EA scope
34+
2. **Poll for status**: Check the operation status until the report is complete
35+
3. **Download the report**: Use the provided download URL to get the CSV file with your cost data
36+
37+
> [!NOTE]
38+
> 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 1-year reservation costing $365 will appear in ActualCost as a single charge on the purchase date. In AmortizedCost, that same $365 is spread out as a daily $1.00 charge across the usage that benefits from the reservation.
3239
33-
|Request header|Description|
34-
|--------------------|-----------------|
35-
|*Content-Type:*|Required. Set to `application/json`.|
36-
|*Authorization:*|Required. Set to a valid `Bearer` API key. |
40+
## Working with different EA scopes
3741

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.
42+
The Cost Details API supports three EA scopes, each providing different levels of cost aggregation:
3943

44+
- **Billing account scope**: Cost details for the entire EA billing account
45+
- **Department scope**: Cost details aggregated for all accounts in a specific department
46+
- **Enrollment account scope**: Cost details for a specific account within an enrollment
4047

41-
## Response
48+
## Step 1: Create a cost details report
4249

43-
Status code 200 (OK) is returned for a successful response, which contains a list of detailed costs for the account.
50+
Submit a POST request to generate a Cost Details report:
51+
52+
```http
53+
POST https://management.azure.com/providers/Microsoft.Billing/{scope}/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2025-03-01
54+
Content-Type: application/json
55+
Authorization: Bearer {access-token}
4456
45-
```json
4657
{
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-
]
58+
"metric": "ActualCost",
59+
"timePeriod": {
60+
"start": "2025-07-01",
61+
"end": "2025-07-31"
62+
}
6763
}
68-
```
64+
```
6965

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.
66+
Where `{scope}` varies based on your desired scope:
7167

72-
## Department billing
68+
- **Billing account scope**: `billingAccounts/{billingAccountId}`
69+
- **Department scope**: `departments/{departmentId}`
70+
- **Enrollment account scope**: `enrollmentAccounts/{enrollmentAccountId}`
7371

74-
Get usage details aggregated for all accounts in a department.
72+
## Step 2: Poll for report status
73+
74+
Check the operation status until the report is complete:
7575

7676
```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
77+
GET https://management.azure.com/providers/Microsoft.Billing/{scope}/providers/Microsoft.CostManagement/costDetailsOperationStatus/{operationId}?api-version=2025-03-01
78+
Authorization: Bearer {access-token}
8079
```
8180

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

84-
The following headers are required:
83+
- **Billing account scope**: `billingAccounts/{billingAccountId}`
84+
- **Department scope**: `departments/{departmentId}`
85+
- **Enrollment account scope**: `enrollmentAccounts/{enrollmentAccountId}`
8586

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

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.
89+
When the report status shows "Completed," the response includes a `blobLink` for downloading the CSV file containing the cost details for your selected scope.
9290

93-
### Response
91+
## Request parameters
9492

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.
93+
The request body supports the following parameters:
9694

95+
- **metric** - The type of report requested. Can be either `ActualCost` or `AmortizedCost`. If not specified, defaults to `ActualCost`.
96+
- **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.
97+
- **invoiceId** - The requested invoice for your data. This parameter is supported for Microsoft Customer Agreement customers at the Billing Profile or Customer scope. Can't be used alongside billingPeriod or timePeriod parameters.
98+
- **billingPeriod** - The requested billing period for your data. This parameter is supported for Enterprise Agreement customers. Use the YearMonth format (for example, 202408). Can't be used alongside invoiceId or timePeriod parameters.
9799

98-
The following example shows the output of the REST API for department `1234`.
100+
> [!NOTE]
101+
> If none of the timePeriod, invoiceId, or billingPeriod parameters are provided in the request body, the API returns the current month's cost.
99102
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-
```
103+
The following headers are required:
125104

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.
105+
|Request header|Description|
106+
|--------------------|-----------------|
107+
|*Content-Type:*|Required. Set to `application/json`.|
108+
|*Authorization:*|Required. Set to a valid `Bearer` [access token](/rest/api/azure/#authorization-code-grant-interactive-clients). |
127109

128-
## Enrollment account billing
110+
## Response
129111

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

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-
```
114+
The initial POST request returns status code 202 (Accepted) with response headers:
137115

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

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

142-
|Request header|Description|
143-
|--------------------|-----------------|
144-
|*Content-Type:*|Required. Set to `application/json`.|
145-
|*Authorization:*|Required. Set to a valid `Bearer` API key. |
123+
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.
146124

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.
125+
### Key response fields
148126

149-
### Response
127+
|Response property|Description|
128+
|----------------|----------|
129+
|**status** | Status of the report generation (InProgress, Completed, Failed) |
130+
|**dataFormat** | Format of the generated report (CSV) |
131+
|**blobCount** | Number of blob files in the report dataset |
132+
|**byteCount** | Total size of the report dataset in bytes |
133+
|**blobLink** | Download URL for the Cost Details CSV file |
134+
|**validTill** | Expiration date/time for the download URL |
150135

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.
136+
## Cost Details file fields
152137

153-
The following example shows the output of the REST API for enterprise enrollment `1234`.
138+
The downloaded CSV file contains detailed cost and usage data with key fields including:
154139

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-
```
140+
- **Date** - The usage or purchase date of the charge
141+
- **BillingAccountId** - Unique identifier for the EA billing account
142+
- **InvoiceSectionId** - Unique identifier for the EA department (if applicable)
143+
- **AccountId** - Unique identifier for the EA enrollment account
144+
- **SubscriptionId** - Unique identifier for the Azure subscription
145+
- **ResourceGroup** - Name of the resource group
146+
- **CostInBillingCurrency** - Cost of the charge in the billing currency before credits or taxes
147+
- **ChargeType** - Indicates whether the charge represents usage, a purchase, or a refund
148+
- **PricingModel** - Identifier that indicates how the meter is priced
149+
150+
For a complete list of all fields and their descriptions, see [Understand cost details fields](../automate/understand-usage-details-fields.md).
178151

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.
152+
## Best practices
153+
154+
- **Request frequency**: Generate reports at most once per day for a given scope and date range. Cost data is refreshed every four hours.
155+
- **Date range**: For large datasets, limit the date range (for example, generate daily or weekly reports) to keep file sizes manageable.
156+
- **Data retention**: Download and store reports promptly. The download URL expires after a short period (typically one hour).
180157

181158
## Next steps
182-
- [Get started with Azure REST API](/rest/api/azure/)
159+
160+
- [Get started with Azure REST API](/rest/api/azure/)
161+
- [Learn more about the Cost Details API](/rest/api/cost-management/generate-cost-details-report)
162+
- [Get small cost datasets on demand](../automate/get-small-usage-datasets-on-demand.md)
163+
- [Understand Cost Details fields](../automate/understand-usage-details-fields.md)

0 commit comments

Comments
 (0)