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.
The new commerce daily rated usage reconciliation APIs use advanced techniques like valet key and asynchronous request-reply patterns. 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.
Our APIs use optimized techniques to boost your efficiency, so you can achieve faster results with less effort. Embrace these APIs to simplify your data access and improve your overall efficiency.
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.
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.
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. Here's a streamlined guide to get you started:
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 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. If not specified, "full" is the default value. Check the list of attributes in this section). Optional. |
| billingPeriod | True | String | To get daily rated usage for the current or last calendar month or billing period, use "current" or "last" (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 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 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 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. 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 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, 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 invoice reconciliation API for the "full" or "basic" attribute sets, refer to the following table. 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 |
| 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 from v2.
Each attribute name now starts with an uppercase letter.
unitOfMeasure is updated to Unit. Its meaning and value remain unchanged.
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. For instance, 0.15 is now 15%.
rateOfCredit is now CreditPercentage. Both the name and value have changed. 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.