Billed and unbilled daily rated usage reconciliation API v2 (GA)
Applies to: Partner Center (unavailable in Azure Government, Azure Germany, or Azure China 21Vianet.)
Our asynchronous APIs offer a faster and more manageable way to access billing and reconciliation data through Azure blobs. With these APIs, you don't need to keep the connection open for hours or loop through the batches of 2,000 line items.
We optimized our daily rated usage reconciliation APIs using valet key and asynchronous request-reply patterns. When you use these APIs, you receive a token that you can use to access either all the attributes or a subset of the daily rated usage reconciliation data.
Note
The new APIs aren't hosted on the Partner Center API host. Instead, you can find them on MS Graph at Use the Microsoft Graph API to export partner billing data - Microsoft Graph v1.0 | Microsoft Learn. To access these APIs, refer to the following details.
You can use these APIs for the MS Graph public/global cloud only now. They aren't yet available for Azure Government, Azure Germany, or Azure China 21Vianet.
Note
If you've been using our beta version, you may not notice significant changes in the generally available (GA) version. We recommend comparing the two versions to understand the differences and updates.
Important
The daily rated usage data doesn't include the charges for these products:
- Azure reservation
- Azure savings plan
- Office
- Dynamics
- Microsoft Power Apps
- Perpetual software
- Software subscription
- Third-party SaaS product
API overview
To retrieve daily rated usage data asynchronously, use two API endpoints. Here's the process:
Usage line-item endpoint
Use this API to retrieve billed or unbilled daily rated usage line items. The API returns a 202 HTTP status and a location header containing the URL. Poll this URL at regular intervals until you receive a success status with a manifest URL.
Operation status endpoint
To get a success status, keep calling this API at a regular interval. If the data isn't ready, the API response includes a Retry-After header to tell you how long to wait before trying again. When the operation is complete, you get a manifest resource with a storage folder where you can download the usage data. The response breaks up the files into smaller pieces for optimized throughput and I/O parallelism.
Sequence diagram
Here's a sequence diagram that shows the steps for downloading the reconciliation data.
User action sequence
To retrieve daily rated usage reconciliation data, follow these steps:
Step 1: Submit request
Submit a POST request to the API endpoint.
Get unbilled daily rated usage line items
Get unbilled daily rated usage line items for the current or last calendar month or billing period.
API request
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
Accept: application/json
Content-Type: application/json
{
"currencyCode": "USD",
"billingPeriod": "current",
"attributeSet": "basic"
}
Request body
| Attribute | Required | Type | Description |
|---|---|---|---|
| attributeSet | False | String | Choose "full" for all attributes or "basic" for a limited set. The default value is "full." (See the list of attributes here). Optional. |
| billingPeriod | True | String | Use "current" or "last" (same as "previous" in V1 APIs) to get daily rated usage for the current or last calendar month or billing period. Required. |
| currencyCode | True | String | Partner billing currency code. Required. |
Request headers
To request headers for the API, see Reliability and support.
API response
HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
When you use the API, it typically returns an HTTP 202 status. To see other possible statuses based on your requests, see Standard API response statuses.
| Code | Description |
|---|---|
| 202 – Accepted | Your request was accepted. To check the status of your request, query the URL provided in the location header. |
Get billed daily rated usage line items
Get billed daily rated usage line items for an invoice for the closed billing period.
API request
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
{
"invoiceId": "G00012345",
"attributeSet": "full"
}
Query parameters
N/A
Request body
| Attribute | Required | Type | Description |
|---|---|---|---|
| invoiceId | True | String | A unique identifier for each invoice. Required. |
| attributeSet | False | String | Choose "full" for all attributes or "basic" for a limited set. The default value is "full." (See the list of attributes here). Optional. |
Request header
Request headers for the API. To learn more, see the reliability and support.
API response
HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
When you use the API, it typically returns an HTTP 202 status. For other possible statuses based on your requests, see Statuses.
| Code | Description |
|---|---|
| 202 – Accepted | Your request was accepted. To check the status of your request, query the URL provided in the location header. |
Step 2: Check request status
To check the status of a request, wait for an HTTP 200 response with a status of either "succeeded" or "failed." If the request is successful, the manifest URL is provided in the "resourceLocation" attribute.
Get Operation status
Retrieves the status of a request.
API request
Request parameters
| Name | Include in | Required | Type | Description |
|---|---|---|---|---|
| operationId | Request URI | True | String | A unique ID to check the request status. Required. |
Request header
To request headers for the API, see Reliability and support.
Request body
N/A.
Response status
In addition to the standard HTTP statuses, the API can return the following HTTP status:
| Code | Description |
|---|---|
| 410 – Gone | The manifest link is only active for a specific duration set by the server. After this time elapses, you must submit a new request to access the manifest. |
Response payload
The API response payload includes the following attributes:
| Attribute | Required | Description |
|---|---|---|
| id | True | A unique ID for each response. Required. |
| status | True | Values and actions (required): notstarted: Wait for the time specified in the "Retry-After" header, then make another call to check the status. running: Wait for the time specified in the "Retry-After" header, then make another call to check the status. succeeded: The data is ready. Retrieve the manifest payload using the URI specified in resourceLocation. failed: The operation failed permanently. Restart it. |
| createdDateTime | True | The time when the request was made. Required. |
| lastActionDateTime | True | The time the status was last changed. Required. |
| resourceLocation | False | The URI for the manifest payload. Optional. |
| error | False | If the operation fails, error details are provided in JSON format. Optional. The following attributes might be included: message (Required): A detailed description of the error. code (Required): The type of error that occurred. |
Resource location object
| Attribute | Description |
|---|---|
| id | A unique identifier for the manifest. |
| schemaVersion | Version of the manifest schema. |
| dataFormat | Format of the billing data file. compressedJSON: data format where each blob is a compressed file that contains data in JSON lines format. To retrieve the data from each blob, decompress it. |
| createdDateTime | Date and time when the manifest file was created. |
| eTag | Version of the manifest data. A change in billing information generates a new value. |
| partnerTenantId | ID of the partner's tenant. |
| rootDirectory | Root directory of the file. |
| sasToken | SAS (shared access signature) token that allows you to read all files under the directory. |
| partitionType | Divides data into multiple blobs based on the "partitionValue" attribute. The system splits partitions that exceed the supported number. By default, data is partitioned based on the number of line items in the file. Don't set a fixed number of line items or file size in the code, as these values might change. |
| blobCount | Total number of files for this partner tenant ID. |
| blobs | A JSON array of "blob" objects that contain the file details for the partner tenant ID. |
| blob object | An object that contains the following details: |
| name | Name of the blob. |
| partitionValue | Partition that contains the file. The large partition is split into multiple files, with each file containing the same "partitionValue". |
API request
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API response
The response recommends waiting for 10 seconds before trying again when processing data.
HTTP/1.1 200 OK
Retry-After: 10
{
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-05Z",
"status": "running"
}
API request
(10 seconds after the previous request…)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API response
The API returns the "succeeded" status and the URI for "resourceLocation."
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",
"@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",
"id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",
"createdDateTime": "2023-12-05T21:17:29Z",
"lastActionDateTime": "2023-12-05T21:18:00.8897902Z",
"status": "succeeded",
"resourceLocation": {
"id": "44e8500b-ab92-490e-8ac3-90500a1d3427",
"createdDateTime": "2023-11-06T19:58:47.513Z",
"schemaVersion": "2",
"dataFormat": "compressedJSON",
"partitionType": "default",
"eTag": "RwDrn7fbiTXy6UULE",
"partnerTenantId": "0e195b37-4574-4539-bc42-0e539b9684c0",
"rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",
"sasToken": "{token}",
"blobCount": 1,
"blobs": \[
{
"name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",
"partitionValue": "default"
}
\]
}
}
Step 3: Download daily rated usage reconciliation data from Azure blob storage
Get the shared access signature (SAS) token and the blob storage location from "sasToken" and "rootDirectory" properties the manifest payload API response. Use the Azure Storage SDK/tool to download and unzip the blob file. It's in JSONLines format.
Standard API response statuses
You might receive these HTTP statuses from the API response:
| Code | Description |
|---|---|
| 400 – Bad Request | The request is missing or contains incorrect data. Check the response body for error details. |
| 401 – Unauthorized | Caller isn't authenticated, and you must authenticate with the partner API service before making the first call. |
| 403 – Forbidden | You don't have the necessary authorization to make the request. |
| 404 – Not Found | The requested resources aren't available with the provided input parameters. |
| 410 – Gone | The manifest link timed out or expired. Submit a new request. |
| 500 – Internal Server Error | The API or one of its dependencies can't fulfill the request right now. Try again later. |
Compare beta and GA versions
See the comparison table to understand the differences between the beta and generally available (GA) versions. If you're using the beta version, switching to the GA version should be straightforward.
| Important information | Beta | Generally available |
|---|---|---|
| API host endpoint | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/ |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/ |
| HTTP method | POST | POST |
| Unbilled daily rated usage API endpoint | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export |
| Input parameters for the unbilled daily rated usage API | To specify parameters in the API request, include them in the query string of the request URL. For example, to specify the period and currencyCode parameters, append ?period=current¤cyCode=usd to the request URL. |
To provide inputs, include a JSON object in the request body. The JSON object should contain the following properties: * currencyCode: The currency code for the invoice. For example, USD. * billingPeriod: The billing period for the invoice. For example, current. Here's an example of a JSON object that includes the currencyCode and billingPeriod properties: <br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>} |
| Billed daily rated usage API endpoint | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId} |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export |
| Input parameters for the billed daily rated usage API | To specify parameters in the API request, include the invoiceId in the request URL. Additionally, you can include an optional fragment parameter in the query string to retrieve the full set of attributes. For example, to retrieve the full set of attributes, append ?fragment=full to the request URL. |
To provide inputs, include a JSON object in the request body. The JSON object should contain the following properties: * invoiceId: The ID of the invoice. For example, G00012345. * attributeSet: The set of attributes to include in the response. For example, full. Here's an example of a JSON object that includes the invoiceId and attributeSet properties: {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>} |
| Manifest resource | Use a separate GET /manifests/{id} method to retrieve the manifest resource. | Use GET /operations/{Id} method, which returns the related manifest resource in resourceLocation eliminating the need for a separate call to GET /manifests/{id} method. |
| Changes to the manifest schema | ||
| "id": Not available | "id": A unique identifier for the manifest resource. | |
| "version": Available | "version": renamed to "schemaversion." | |
| "dataFormat": Available | "dataFormat": Available. | |
| "utcCretedDateTime": Available | "utcCretedDateTime": renamed to "createdDateTime." | |
| "eTag": Available | "eTag": Available. | |
| "partnerTenantId": Available | "partnerTenantId": Available | |
| "rootFolder": Available | "rootFolder": renamed to "rootDirectory." | |
| "rootFolderSAS": Available | "rootFolderSAS": renamed to "sasToken." It now provides a token and no longer includes the root directory path. To access the directory, use "rootDirectory" property instead. | |
| "partitionType": Available | "partitionType": Available. | |
| "blobCount": Available | "blobCount": Available. | |
| "sizeInBytes": Available | "sizeInBytes": Not available. | |
| "blobs": Available | "blobs": Available. | |
| "blob object": Available | "blob object": Available. | |
| "name": Available | "name": Available. | |
| "partitionValue": Available | "partitionValue": Available. |
Daily rated usage reconciliation data attributes
To compare the attributes returned by the daily rated usage reconciliation API for the "full" or "basic" attribute sets, refer to the following information.
| Attribute | Full | Basic |
|---|---|---|
| PartnerId | yes | yes |
| PartnerName | yes | yes |
| CustomerId | yes | yes |
| CustomerName | yes | Yes |
| CustomerDomainName | yes | no |
| CustomerCountry | yes | no |
| MpnId | yes | no |
| Tier2MpnId | yes | no |
| InvoiceNumber | yes | yes |
| ProductId | yes | yes |
| SkuId | yes | yes |
| AvailabilityId | yes | no |
| SkuName | yes | yes |
| ProductName | yes | no |
| PublisherName | yes | yes |
| PublisherId | yes | no |
| SubscriptionDescription | yes | no |
| SubscriptionId | yes | yes |
| ChargeStartDate | yes | yes |
| ChargeEndDate | yes | yes |
| UsageDate | yes | yes |
| MeterType | yes | no |
| MeterCategory | yes | no |
| MeterId | yes | no |
| MeterSubCategory | yes | no |
| MeterName | yes | no |
| MeterRegion | yes | no |
| Unit | yes | yes |
| ResourceLocation | yes | no |
| ConsumedService | yes | no |
| ResourceGroup | yes | no |
| ResourceURI | yes | yes |
| ChargeType | yes | yes |
| UnitPrice | yes | yes |
| Quantity | yes | yes |
| UnitType | yes | no |
| BillingPreTaxTotal | yes | yes |
| BillingCurrency | yes | yes |
| PricingPreTaxTotal | yes | yes |
| PricingCurrency | yes | yes |
| ServiceInfo1 | yes | no |
| ServiceInfo2 | yes | no |
| Tags | yes | no |
| AdditionalInfo | yes | no |
| EffectiveUnitPrice | yes | yes |
| PCToBCExchangeRate | yes | yes |
| EntitlementId | yes | yes |
| EntitlementDescription | yes | no |
| PartnerEarnedCreditPercentage | yes | no |
| CreditPercentage | yes | yes |
| CreditType | yes | yes |
| BenefitOrderID | yes | yes |
| BenefitID | yes | no |
| BenefitType | yes | yes |
Important
Make note of these changes when switching to API v2 from v1.
Each attribute's name starts in uppercase.
unitOfMeasure is now Unit. The attribute's meaning and value are the same.
resellerMpnId is now Tier2MpnId. The attribute's meaning and value are the same.
The name and value of rateOfPartnerEarnedCredit have changed to PartnerEarnedCreditPercentage. The attribute's new name and value reflect the percentage instead of the fraction. For example, 15 is now 0.15.
rateOfCredit is now CreditPercentage. The attribute's meaning and value have changed. For example, 1.00 is now 100.
Sample code
To learn more, see Partner Center API samples: Get billing recon data.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for