Applies to: Partner Center | Partner Center operated by 21Vianet | Partner Center for Microsoft Cloud for US Government
Use these APIs to get new commerce billed and unbilled daily rated usage data asynchronously.
Note
This API will be deprecated soon. To ensure seamless operations, we recommend migrating to the GA version. Here are the details you need to plan ahead:
Goal: Retrieve billed daily rated usage line items for billing periods from September 2022 before January 21, 2025.
Action: Use this API but migrate to v2 GA as soon as possible.
Goal: Retrieve billed daily rated usage line items for billing periods from September 2022 from January 21, 2025.
Action: Use only API v2 GA.
Goal: Retrieve unbilled daily rated usage line items for the current and previous billing periods before January 21, 2025.
Action: Use this API but migrate to v2 GA as soon as possible.
Goal: Retrieve unbilled daily rated usage line items for the current and previous billing periods from January 21, 2025.
Thank you for your attention, and we look forward to your continued success with our billing APIs.
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.
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
Non-Microsoft or marketplace SaaS product
API overview
The asynchronous API is a novel method for quickly accessing billing and reconciliation data in manageable chunks. It eliminates the need to maintain an open connection for hours and loop through millions of transactions iteratively.
We use valet key and asynchronous request-reply patterns to optimize our invoicing and reconciliation APIs to deliver the results asynchronously. API responses provide a token to access the reconciliation data with all the attributes or a subset.
You can download the usage data asynchronously using three new steps (API endpoints). To learn more, read following sections:
Usage line-item endpoint
Use this API to access billed or unbilled consumption line items. It returns a 202 HTTP status and a location header with the URL, which you must poll at regular intervals until you receive a success status with a manifest URL.
Operation status endpoint
Until you receive the success status, keep polling this API at a regular interval. If the requested data is unavailable, the API response includes a Retry-After header indicating how long you should wait before sending another request.
Manifest endpoint
This endpoint provides a storage folder from which actual billing data can be downloaded. The response splits or partitions the files to optimize throughput and I/O parallelism.
Sequence diagram
The diagram depicts the steps needed to download reconciliation data.
User action sequence
Follow these steps to retrieve reconciliation data.
Step 1: Submit request
Submit a POST request to the API endpoint.
Get unbilled usage line items
Get unbilled usage line items for the current or last calendar month.
API request
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
Request parameters
Name
In
Required
Type
Description
fragment
Query
False
String
Choose "full" for a complete response or "basic" for a subset of attributes. The default value is "full." See the list of attributes in this article.
period
Query
True
String
Use "current" or "last" to get usage for the current or last calendar month. The value "last" is the same as "previous" in existing V1 APIs.
currencyCode
Query
True
String
Partner billing currency code.
Deprecated request parameters
The newer API version doesn't require the following URI parameters:
Name
Description
Provider
N/A. (It returns all Azure plan usage and is equivalent to the "onetime" of existing V1 APIs.)
Each manifest link is active for a specified amount of server-controlled time. After the time elapsed, the client must submit a new request.
Response payload
The API response returns the following attributes:
Name
Description
Version
The manifest schema version.
dataFormat
The billing data file format. Possible values compressedJSONLines: each blob is a compressed file and data in the file is in JSON lines format. To access the data, decompress the file.
utcCreatedDateTime
Manifest file creation time.
eTag
Manifest data version. A change in billing information generates a new eTag value.
partnerTenantId
Partner tenant ID.
rootFolder
The file's root directory.
rootFolderSAS
The SAS token for accessing the file.
partitionType
This property divides the data. If a given partition has more than the supported number, the data is split into multiple files corresponding to the "partitionValue." By default, the system partitions data based on the number of line items in the file. Don't set a fixed number of line items or file size in your code because the partitioning principle might change.
blobCount
Total file count for this partner tenant ID.
sizeInBytes
Total bytes in all the files.
blobs
A JSON array of "blob" objects having the details of all the files for the partner tenant ID.
Blob object
Name
Blob's name.
sizeInBytes
Blob size in bytes.
partitionValue
The partition that contains the file. A large partition will be split into multiple files, each with the same "partitionValue."
Step 4: Download usage reconciliation data from storage location
Get the SAS token and the blob storage location from "rootFolderSAS" and "rootFolder" properties the manifest payload API response. Use the Azure Storage SDK/tool to download and unzip the blob file. It’s in JSON lines format.
Standard API request headers
All APIs accept the following headers:
Name
Required
Type
Description
Authorization
True
String
Authorization Bearer Token.
ms-correlationid
False
String
An internal request tracker. Each request generates a new tracker (GUID).
ms-cv
False
String
An internal request tracker.
ms-requestid
False
String
The request idempotency ID.
Standard API response statuses
The following are the HTTP statuses from the API response:
Name
Description
400 Bad Request
There was missing or incorrect data. The error details are included in the response body.
401 Unauthorized
The caller isn't authenticated and must authenticate with the partner API service before making the first call.
403 Forbidden
The caller isn't authorized to make the request.
500 Internal Server Error
The API or one of its dependencies is unable to fulfill the request. Try again later.
404 Not Found
Resource not available with input parameters.
410 Gone
The manifest link timed out or elapsed. Submit a new request.
Usage data attributes
The billed or unbilled usage API response with the "full" or "basic" request parameter returns the following attributes:
With the Partner Center, Cloud Solution Provider partners can view and manage invoices, reconciliation line items, and customer's Azure spending budget programmatically.