Invoicing and reconciliation 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 billed and unbilled daily rated usage data asynchronously.
Note
This API for billed daily rated usage will stop working after June 30, 2024. Refer to the following details to decide which version to use and when.
- Unless you've switched to v2 GA, use this API until June 30, 2024, to get billed daily rated usage line items for invoices that are created for billing periods between September 2022 and June 2024.
- Use only API v2 GA after June 30, 2024, to get billed daily rated usage line items for invoices that are created for billing periods from September 2022.
This API for unbilled daily rated usage will stop working after June 30, 2024. Refer to the following details to decide which version to use and when.
- Unless you've switched to v2 GA, use this API until June 30, 2024, to get unbilled daily rated usage line items for current and previous billing periods.
- Use only API v2 GA after June 30, 2024, to get unbilled daily rated usage line items for current and previous billing.
To start preparing for the migration to the new v2 GA APIs, see the following link:
Billed and unbilled daily rated usage reconciliation API v2 (GA)
Note
You can retrieve your daily unbilled usage data through the API or Partner Center portal. It can take up to 24 hours for the data to become available. However, there might be further delays depending on your location and when the meters report the usage.
Sometimes, you might not see the most recent unbilled usage data until the billed usage data for the previous month is delivered. This is done to ensure that billed usage data is delivered within the agreed time. Once you receive the billed usage data, you should be able to retrieve all the updated unbilled usage data from the start of the month.
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
- Third-party 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've used valet key and asynchronous request-reply patterns to optimize our invoicing and reconciliation APIs to deliver the results asynchronously. API responses will 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 the following:
Usage line-item endpoint
Use this API to access billed or unbilled consumption line items. It will return 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 will include 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 below depicts the steps needed to download reconciliation data.
User action sequence
Follow the steps below 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 has been 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 has been 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 will be "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 below HTTP status:
| Name | Description |
|---|---|
| 410 Gone | Each operation link is active for a specified amount of server-controlled time. After the time has 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 below HTTP status:
| Name | Description |
|---|---|
| 410 Gone | Each manifest link is active for a specified amount of server-controlled time. After the time has 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. Decompress the file to access the data. |
| 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 will be split into multiple files corresponding to the "partitionValue." Data is partitioned by the number of line items in the file by default. Don't set a fixed number of line items or file size in your code because these 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": "14f593ad-1edc-474d-aaa0-83abbf9638da",
"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
Download the reconciliation data from Azure blob storage using the SAS token in the manifest payload. Use the Microsoft Azure Storage SDK/tool to download blobs and uncompress or unzip the blob file before reading its data. The data is 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. Please try again later. |
| 404 Not Found | Resource not available with input parameters. |
| 410 Gone | The manifest link has 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 |
| EntitlementId | yes | yes |
| EntitlementDescription | yes | no |
| PartnerEarnedCreditPercentage | yes | no |
| CreditPercentage | yes | yes |
| CreditType | yes | yes |
| BenefitOrderID | yes | yes |
| BenefitID | yes | no |
| BenefitType | yes | yes |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for