Billed invoice reconciliation API v2 (GA)
Applies to: Partner Center (unavailable in sovereign cloud)
Our asynchronous API offers a faster and more manageable way to access billing and reconciliation data through Azure blobs. With this API, you don't need to keep a connection open for hours or loop through the batches of 2,000 line items at a time.
We have optimized our billed invoice reconciliation API using valet key and asynchronous request-reply patterns. This API provides you with a shared access signature (SAS) token that you can use to access either all the attributes or a subset of the billed invoice reconciliation data.
Note
The new API isn't hosted on the Partner Center API host. Instead, you can find it on MS Graph at Use the Microsoft Graph API to export partner billing data - Microsoft Graph v1.0. To access this API, refer to the following details.
You can use this API only for the MS Graph public/global cloud now. It isn't yet available for Azure Government, Azure Germany, or Azure China 21Vianet.
API overview
To retrieve billed invoice reconciliation data asynchronously, use two API endpoints. Here's the process:
Billed invoice reconciliation endpoint
Use this API to retrieve billed invoice reconciliation line items. The API returns a 202 HTTP status and a location header containing a URL. Poll this URL at regular intervals until you receive a success status with a manifest URL.
Operation status endpoint
To get a success status, keep calling this API at a regular interval. If the data isn't ready, the API response includes a Retry-After header to tell you how long to wait before trying again. When the operation is complete, you get a manifest resource with a storage folder where you can download the usage data. The response breaks up the files into smaller pieces for optimized throughput and I/O parallelism.
Sequence diagram
Here's a sequence diagram that shows the steps for downloading the reconciliation data.
User action sequence
To retrieve billed invoice reconciliation data, follow these steps:
Step 1: Submit request
Submit a POST request to the API endpoint.
Get billed invoice reconciliation line items
API request
POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export
Accept: application/json
Content-Type: application/json
{
"invoiceId": "G016907411",
"attributeSet": "basic"
}
Query parameters
N/A
Request body
| Attribute | Required | Type | Description |
|---|---|---|---|
| attributeSet | False | String | Choose "full" for all attributes or "basic" for a limited set. The default value is "full." (See the list of attributes in this article). Optional. |
| invoiceId | True | String | A unique identifier for each invoice. Required. |
Request headers
Request headers for the API using the steps listed at Best practices for using Microsoft Graph.
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. Other possible statuses, based on your requests, are listed in Standard API response statuses in this article.
| 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 check the status of a request, wait for an HTTP 200 response with a status of either "succeeded" or "failed." You get the manifest URL in "resourceLocation" attribute if the request is successful.
Get Operation status
Retrieves the status of a request.
API request
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Request parameters
| Name | Include in | Required | Type | Description |
|---|---|---|---|---|
| operationId | Request URI | True | String | A unique ID to check the request status. Required. |
Request header
Request headers for the API using the steps listed at Best practices for using Microsoft Graph.
Request body
N/A.
Response status
In addition to the standard HTTP statuses listed in Standard API response statuses in this article, the API can 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 ID 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 time the status was last changed. Required. |
| resourceLocation | False | The URI for the manifest payload. Optional. |
| error | False | If the operation fails, error details are provided in JSON format. Optional. The following attributes are included: message: A detailed description of the error. code: The type of error that occurred. |
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 | 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 can 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 that contains the following details: 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." |
| 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 your data is still processing.
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": "0e195b37-4574-4539-bc42-0e539b9684c0",
"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 billed invoice reconciliation data from Azure blob storage
Get the shared access signature (SAS) token and the blob storage location from "sasToken" and "rootDirectory" properties the manifest payload API response. Azure Storage SDK/tool to download and unzip the blob file. It's in the JSONLines format.
Tip
Check out our sample code to download and unzip the Azure blob file to your local database.
Standard API response statuses
You might get these HTTP statuses from the response of the API:
| Code | Description |
|---|---|
| 400 – Bad Request | The request is missing or contains incorrect data. Check the response body for error details. |
| 401 – Unauthorized | The caller isn't authenticated, and you must authenticate with the partner API service before making the first call. |
| 403 – Forbidden | You don't have the necessary authorization to make the request. |
| 404 – Not Found | The requested resources aren't available with the input parameters provided. |
| 410 – Gone | The manifest link is no longer valid or active. Submit a new request. |
| 500 – Internal Server Error | The API or one of its dependencies can't fulfill the request right now. Try again later. |
Billed invoice reconciliation data attributes
To compare the attributes returned by the billed invoice reconciliation API for the "full" or "basic" attribute sets, refer to the following table.
| Attribute | Full | Basic |
|---|---|---|
| PartnerId | yes | yes |
| CustomerId | yes | yes |
| CustomerName | yes | yes |
| CustomerDomainName | yes | no |
| CustomerCountry | yes | no |
| InvoiceNumber | yes | yes |
| MpnId | yes | no |
| Tier2MpnId | yes | yes |
| OrderId | yes | yes |
| OrderDate | yes | yes |
| ProductId | yes | yes |
| SkuId | yes | yes |
| AvailabilityId | yes | yes |
| SkuName | yes | no |
| ProductName | yes | yes |
| ChargeType | yes | yes |
| UnitPrice | yes | yes |
| Quantity | yes | no |
| Subtotal | yes | yes |
| TaxTotal | yes | yes |
| Total | yes | yes |
| Currency | yes | yes |
| PriceAdjustmentDescription | yes | yes |
| PublisherName | yes | yes |
| PublisherId | yes | no |
| SubscriptionDescription | yes | no |
| SubscriptionId | yes | yes |
| ChargeStartDate | yes | yes |
| ChargeEndDate | yes | yes |
| TermAndBillingCycle | yes | yes |
| EffectiveUnitPrice | yes | yes |
| UnitType | yes | no |
| AlternateId | yes | no |
| BillableQuantity | yes | yes |
| BillingFrequency | yes | no |
| PricingCurrency | yes | yes |
| PCToBCExchangeRate | yes | yes |
| PCToBCExchangeRateDate | yes | no |
| MeterDescription | yes | no |
| ReservationOrderId | yes | yes |
| CreditReasonCode | yes | yes |
| SubscriptionStartDate | yes | yes |
| SubscriptionEndDate | yes | yes |
| ReferenceId | yes | yes |
| ProductQualifiers | yes | no |
| PromotionId | yes | yes |
| ProductCategory | yes | yes |
Sample code
For guidance on using the API, see the following link that includes sample code in C#.
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