Billed and unbilled daily rated usage reconciliation API v2 (GA)
Applies to: Partner Center (unavailable in Azure Government or Azure China 21Vianet.)
Our new asynchronous API offers a faster and more efficient way to access your billing and reconciliation data through Azure blobs. Instead of keeping a connection open for hours or processing batches of 2,000 line items, you can now streamline your workflow, reduce the server load, and improve data processing times.
The new commerce daily rated usage reconciliation APIs use advanced techniques like valet key and asynchronous request-reply patterns. The valet key pattern allows for secure access to resources without sharing credentials, while the asynchronous request-reply pattern enables efficient communication between systems.
These APIs provide you with a shared access signature (SAS) token that you can use to access either all the attributes or a subset of the daily rated usage reconciliation data. This token enhances security by granting limited time access and offers flexibility in managing data access permissions.
By adopting our optimized APIs, you can achieve faster results with less effort, simplify your data access, and improve overall efficiency. Embrace these tools to streamline your workflow and manage permissions more effectively.
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 allow your app access to partner billing data, follow this link and get familiar with the authentication and authorization basics for Microsoft Graph. This step is crucial as it ensures that your app can securely access the necessary data.
You can assign the "PartnerBilling.Read.All" permission using either the Azure portal or the Entra Admin center. Here's how:
- Register your app on the Microsoft Entra home page under the App registrations section.
- To grant the necessary permission, go to the Microsoft Entra App page. Under the API permissions section, select "Add a permission" and choose the "PartnerBilling.Read.All" scope.
By completing these steps, you ensure that your app has the required access to partner billing data.
Note
If you've been using our beta version, you're likely to find the transition to the general availability (GA) version smooth and intuitive. To help you understand the updates and improvements, we recommend comparing beta and GA versions. Understanding these updates will help you maximize the new features and improvements available in the GA version.
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 help you retrieve billed new commerce daily rated usage line items asynchronously, we offer two key API endpoints. Follow this streamlined guide to get started quickly and efficiently!
Usage line-item endpoint
First, use this API to fetch new commerce daily rated usage line items. When you make a request, you receive a 202 HTTP status and a location header with a URL. Poll this URL regularly until you get a success status and a manifest URL.
Operation status endpoint
Next, keep checking the operation status by calling this API at regular intervals. If the data isn’t ready, the response includes a Retry-After header indicating how long to wait before trying again. Once the operation is complete, you receive a manifest resource with a storage folder link to download the usage data. The response segments the files to enhance throughput and allow for I/O parallelism.
By following these steps, you can efficiently manage your invoice reconciliation process.
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 data accuracy, 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, the most recent unbilled daily rated usage data might not appear until the previous month's billed data is available. Once you receive the billed data, you can then access all updated unbilled usage data from the start of the month.
Key points:
- Allow up to 24 hours for data availability.
- There might be further delays depending on your location and meter reporting times.
- Billed daily rated usage data is prioritized over unbilled data.
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. If not specified, "full" is the default value. Check the list of attributes in this section. Optional. |
| billingPeriod | True | String | To get unbilled daily rated usage, use "current" for the current billing period or "last" for the previous billing period (same as "previous" in v1 API). 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
The API usually responds with an HTTP 202 status. You may also encounter other statuses depending on your requests. These statuses are listed in the Standard API response statuses section.
| 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. If not specified, "full" is the default value. Check the list of attributes in this section. 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 keep track of a request's status, ensure you receive an HTTP 200 response which is a standard status code indicating "succeeded" or "failed." If successful, you find the manifest URL in the "resourceLocation" attribute. This attribute provides an endpoint for accessing the required information.
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 identifier to check the request status. Required. |
Request header
To request headers for the API, see Reliability and support.
Request body
N/A.
Response status
Apart from the standard HTTP statuses listed in Standard API response statuses, the API can also return the following HTTP status:
| Code | Description |
|---|---|
| 410 – Gone | The manifest link expires after a set time. To get the manifest link again, send a new request. |
Response payload
The API response payload includes the following attributes:
| Attribute | Required | Description |
|---|---|---|
| id | True | A unique identifier for each response. Required. |
| status | True | Values and actions: Required: notstarted: Wait for the specified duration in the "Retry-After" header, then make another call to check the status. running: Wait for the specified duration 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 last time the status changed. Required. |
| resourceLocation | False | The URI for the manifest payload. Optional. |
| error | False | Details about any errors, provided in JSON format. Optional. Attributes included: message: Description of the error. code: The type of error. |
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 | Microsoft Entra 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. Avoid hardcoding line item counts or file sizes as they 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 containing the following details: name and partitionValue |
| name | Name of the blob. |
| partitionValue | Partition that contains the file. The large partition is split into multiple files based on certain criteria, such as file size or number of records, 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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"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
First, you need to get the shared access signature (SAS) token and the blob storage location. You can find these details in the "sasToken" and "rootDirectory" properties of the manifest payload API response. Then to download and unzip the blob file, use the Azure Storage SDK/tool. It's in the JSONLines format.
Tip
Make sure to check out our sample code. It shows you how 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 | Authentication is required before making the first call. Authenticate with the partner API service. |
| 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 isn't valid or active anymore. Submit a new request. |
| 500 – Internal Server Error | The API or 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
Check out the comparison table to see the differences between the beta and the generally available (GA) versions. If you're currently using the beta version, transitioning to the GA version is straightforward and easy.
| 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. Your JSON should have the following properties: * currencyCode: Your billing currency. For example, USD. * billingPeriod: The billing period for the invoice. For example, current. Here's a sample 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. Your JSON should have the following properties: * invoiceId: The unique identifier of the invoice. For example, G00012345. * attributeSet: The attributes that should be in the response, like full. Here's a sample 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 the GET /operations/{Id} method to access the manifest resource in resourceLocation. This method saves time by eliminating the need for a separate call to GET /manifests/{id}. |
| Changes to the manifest schema | ||
| "id": Not available | "id": A unique identifier for the manifest resource. | |
| "version": Available | "version": changed to "schemaversion." | |
| "dataFormat": Available | "dataFormat": Available. | |
| "utcCretedDateTime": Available | "utcCretedDateTime": changed to "createdDateTime." | |
| "eTag": Available | "eTag": Available. | |
| "partnerTenantId": Available | "partnerTenantId": Available | |
| "rootFolder": Available | "rootFolder": changed to "rootDirectory." | |
| "rootFolderSAS": Available | "rootFolderSAS": changed to "sasToken." This update provides just the token without the root directory path. To locate the directory, use the "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 billed or unbilled usage reconciliation API for the "full" or "basic" attribute sets, refer to this table. To learn more about these attributes and their meanings, 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 |
| PCToBCExchangeRateDate | yes | no |
| 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 from API v1 to v2.
Each attribute name now starts with an uppercase letter to maintain consistency with the file and improve readability.
unitOfMeasure is updated to Unit. Its meaning and value remain unchanged, simplifying the attribute name.
resellerMpnId is now Tier2MpnId. The meaning and value are the same.
rateOfPartnerEarnedCredit is updated to PartnerEarnedCreditPercentage. The new name and value now reflect the percentage instead of the fraction making it easier to understand. For instance, 0.15 is now 15%.
rateOfCredit is now CreditPercentage. Both the name and value have changed to provide a clearer understanding. For example, 1.00 is now 100%.
We believe these changes make the APIs more intuitive and easier to use.
Sample code
To use this API, see the following link, which includes C# sample code.