Billed and unbilled daily rated usage reconciliation API v2 (GA)
Applies to: Partner Center (unavailable in Azure Government 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 new commerce 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 or Azure China 21Vianet.
Important
To grant your app the necessary permission to access partner billing data, you need to follow this link and learn about the authentication and authorization basics for Microsoft Graph.
Usually, you can use either Azure portal or Entra Admin center to assign the required permission: "PartnerBilling.Read.All." Here are the steps to do so:
- Register your app on the Microsoft Entra home page under the App registrations section.
- Assign permission to your app in the Microsoft Entra App page under the API permissions section. Select “Add a permission” and choose the "PartnerBilling.Read.All" scope.
Note
If you've been using our beta version, you might not notice significant changes in the generally available (GA) version. We recommend comparing the two versions to understand the differences and updates.
Important
The new commerce daily rated usage doesn't include the charges for these products:
- Azure reservation
- Azure savings plan
- Office
- Dynamics
- Microsoft Power Apps
- Perpetual software
- Software subscription
- Non-Microsoft or marketplace SaaS product
API overview
To retrieve new commerce daily rated usage line items 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. You get a 202 HTTP status and a URL in the location header. 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 new commerce daily rated usage reconciliation line items, follow these steps:
Step 1: Submit request
Submit a POST request to the API endpoint.
Get unbilled daily rated usage line items
Get new commerce unbilled daily rated usage line items for the current or last calendar month or billing period.
Note
You can access your unbilled daily rated usage line items through the API or Partner Center portal. To ensure accurate data, allow up to 24 hours for availability. Depending on your location and when the meters report the usage, there might be further delays.
We prioritize on time delivery of billed daily rated usage data first. Occasionally, you might not see the most recent unbilled daily rated usage data until the previous month's billed usage data is available. Once you receive the billed usage data, you can then retrieve all the updated unbilled usage data from the start of the month.
Your understanding and patience are appreciated as we strive to provide the most accurate and timely information possible.
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 new commerce 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 line items 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.
Tip
Check out our sample code to download and unzip the Azure blob file to your local database.
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. |
5000 – No data available | The system has no data for the provided input parameters. |
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 line item 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. To learn more about these attributes, see this documentation.
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 moving 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, 0.15 is now 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.