New commerce daily rated usage v2 API (beta)
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.
Action: Use only API v2 GA.
For a seamless transition to the new APIs, follow this link: Billed and unbilled daily rated usage reconciliation API v2 (GA).
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.) |
| hasPartnerEarnedCredit | N/A. (returns all data, regardless of PEC.) |
| Size | N/A. |
| Offset | N/A. |
| seekOperation | N/A. |
Request header
See the list of request headers for the API in this article.
Request body
N/A.
API response
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/811bb8f0-8aca-4807-897c-c15ce50820d6
API returns HTTP status 202. Based on request, API can return other standard status.
| Name | Description |
|---|---|
| 202 Accepted | The request is accepted. Query the operation-location header URL for the request status. |
Get billed usage line items
Get billed rated usage line items for the closed billing period.
API request
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
Request parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| invoiceId | Path | True | String | The Partner Center invoice number. |
| 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. |
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.) |
| hasPartnerEarnedCredit | N/A. (returns all data, regardless of PEC.) |
| Size | N/A. |
| Offset | N/A. |
| seekOperation | N/A. |
Request header
See the list of request headers for the API in this article.
Request body
N/A.
API response
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e83ab1d4640
API returns "HTTP 202 Accepted." Based on request API can return other standard status.
| Name | Description |
|---|---|
| 202 Accepted | The request is accepted. Check the request status by polling the operation-location header URL. |
Step 2: Check request status
Wait for an HTTP 200 with a terminal status of succeeded or failed. The manifest URL is the "resourceLocation" in the success status.
Get operation status
Gets the status of a reconciliation data request.
API request
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
Request parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| operationId | Path | True | String | The operation ID. |
Request header
See the list of request headers for the API in this article.
Request body
N/A.
Response status
In addition to the standard HTTP status in this article, the API can return this HTTP status:
| Name | Description |
|---|---|
| 410 Gone | Each operation 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 payload returns the following attributes:
| Name | Optional | Description |
|---|---|---|
| createdDateTime | false | Request time. |
| lastActionDateTime | false | Status change time. |
| resourceLocation | true | The manifest payload URI. |
| status | false | Possible values and actions. |
| Value | Client action |
|---|---|
| notstarted | Make another call to check the status after waiting for the time specified in the "Retry-After" header. |
| running | Make another call to check the status after waiting for the time specified in the "Retry-After" header. |
| succeeded | The final state of operation, which indicates that data is ready. Retrieve the manifest payload using the URI specified in resourceLocation. |
| failed | Terminal state, which indicates permanent failure. Restart the operation. |
For error attribute:
| Name | Optional | Description |
|---|---|---|
| error | true | Error details provided in json format if the status of operation is failed. |
| Name | Optional | Description |
|---|---|---|
| message | false | Describes the error in detail |
| code | false | Indicates the kind of error that occurred |
API request
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
API response
The response suggests waiting 10 seconds before retrying when processing data.
HTTP/1.1 200 OK
Retry-After: 10
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime":" 2022-06-1T10-01-05Z",
"status": "running"
}
API request
(10 seconds after the earlier request)
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
API response
The API returns the "succeeded" status and the "resourceLocation" URI.
HTTP/1.1 200 OK
Content-Type: application/json
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-13Z",
"status": "succeeded",
"resourceLocation": "https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/e03e1882-ff59-4c09-882f-74e60b4d7743"
}
Step 3: Get manifest payload
The caller makes a GET request to the manifest URL to learn more about where the reconciliation data is stored in Azure blobs.
Getting the manifest
Retrieves the manifest having information about the Azure storage location of the reconciliation data.
API request
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
Request parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| manifestId | Path | True | String | The manifest ID. |
Request header
See the [list of request headers for the API] in this article.
Request body
N/A.
Response status
In addition to the standard HTTP status, the API can return this HTTP status:
| Name | Description |
|---|---|
| 410 Gone | 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." |
Sample manifest payload
{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"rootFolder": "https://{billing.blob.core.windows.net}/{folder_path}",
"rootFolderSAS": "\*\*\*",
"partitionType": "ItemCount",
"blobCount": 3,
"sizeInBytes": 2000,
"blobs": [
{
"name": "{blobName1.json.gz}",
"sizeinBytes": 500,
"partitionValue": "1"
},
{
"name": "{blobName2.json.gz}",
"sizeinBytes": 1000,
"partitionValue": "2"
},
{
"name": "{blobName3.json.gz}",
"sizeinBytes": 500,
"partitionValue": "3"
}
]
}
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:
| 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 |