Billed invoice reconciliation API v2 (GA)
Applies to: Partner Center (unavailable in Azure Government or Azure China 21Vianet)
Understand the architecture
The new asynchronous API offers significant advancements in how we handle billing and reconciliation data access. This approach resolves challenges associated with traditional synchronous methods, like maintaining long-lived connections and processing large data batches. Here are the key benefits and mechanisms of this API:
Key components
Secure access with valet key pattern
The valet key pattern provides secure, limited access to your billing data. Similar to how a valet key allows someone to drive your car without accessing the trunk, this pattern ensures granular access control. Instead of sharing credentials, a shared access signature (SAS) token grants limited, time-bound access to specific resources. This pattern reduces the risk of unauthorized access by configuring precise expiration times and access permissions.
Enhanced efficiency through asynchronous request-reply pattern
Think of it as ordering at a busy restaurant. Instead of waiting at the counter, you receive a buzzer and can do other things while your order is prepared. When the data is ready, the system notifies you.
The asynchronous nature of the API means you make a request and the system processes it in the background. This asynchronous request-reply efficiently uses resources, reduces server load, and minimizes timeouts and failures common with synchronous data retrieval.
Flexibility in data access permissions
SAS tokens offer flexibility in managing data access permissions. You can generate tokens that grant access to all attributes of the billed invoice reconciliation data or limit access to specific subsets. This granularity enables organizations to tailor data access according to internal policies and regulatory requirements, enhancing security and compliance.
Simplified workflow and improved data processing times
The asynchronous request-reply pattern streamlines data processing by allowing dynamic access instead of fixed batches of 2,000 line items. This approach leads to faster results and improved processing times, simplifying the integration of billing and reconciliation data into existing systems and workflows.
Benefits
Performance benefits
Instead of maintaining long-lived connections and processing fixed batches, the new system allows you to:
Make a quick initial request.
Receive a secure access token.
Process data at your own pace.
Access exactly what you need when you need it.
Security improvements
The valet key pattern, implemented through SAS tokens, provides:
Time-limited access.
Restricted permissions.
Elimination of sharing or storing permanent credentials.
Fine-grained access control.
Architectural advantages
The asynchronous request-reply pattern acts like a personal assistant who:
Takes your request.
Handles the task in the background.
Notifies you when everything is ready.
Adopt optimized APIs for enhanced performance
Embracing these optimized APIs streamlines workflow and enhances overall performance in data management. Using secure access control and efficient retrieval mechanisms, you achieve better results with less effort, leading to improved operational efficiency.
In conclusion, the new asynchronous API for accessing billing and reconciliation data through Azure blobs is a powerful tool. It offers secure, efficient access to financial data, streamlining workflows, reducing server loads, and improving processing times, all with high security and compliance.
Note
The new API isn't hosted on the Partner Center API host. Instead, you can find it on Microsoft 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.
Allow your app to securely access partner billing data
To allow your app to access partner billing data, follow this link and get familiar with the authentication and authorization basics for Microsoft Graph. This step is crucial as it ensures that your app can securely access the necessary data.
Register your app and assign PartnerBilling.Read.All permission
You can assign the "PartnerBilling.Read.All" permission using either the Azure portal or the Microsoft Entra admin center. By completing these steps, you help ensure that your app has the required access to partner billing data. Here's how:
- Register your app on the Microsoft Entra home page under the App registrations section.
- Grant the necessary permission by going to the Microsoft Entra App page. Under the API permissions section, select Add a permission and choose the PartnerBilling.Read.All scope.
Learn about the key API endpoints
To help you retrieve billed new commerce invoice reconciliation line items asynchronously, we offer two key API endpoints. These endpoints help you efficiently manage your invoice reconciliation process. Follow this streamlined guide to get started quickly.
Use the billed invoice reconciliation endpoint
First, use this API to fetch new commerce billed invoice reconciliation 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.
Use the 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 completes, 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.
Review the sequence diagram
Here's a sequence diagram that shows the steps for downloading new commerce invoice reconciliation data.
Follow the user action sequence to retrieve billed invoice reconciliation data
Here's the user action sequence to retrieve billed invoice reconciliation data:
- Submit a POST request
- Check request status
- Download reconciliation line items from Azure blob storage
Submit a POST request
Submit a POST request to the API endpoint.
Get billed invoice reconciliation line items
Get the 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. If not specified, "full" is the default value. Check the list of attributes in this section. 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. By following these guidelines, you ensure reliability and support for your application. Your attention to detail in this step is crucial for seamless integration and optimal performance.
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 might 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. |
Check the request status
To keep track of a request's status, ensure you receive an HTTP 200 response which is a standard status code 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
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 identifier to check the request status. Required. |
Request header
Request headers for the API using the steps listed at Best practices for using Microsoft Graph. By following these guidelines, you ensure reliability and support for your application. Your attention to detail in this step is crucial for seamless integration and optimal performance.
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 specified duration in the "Retry-After" header, then make another call to check the status. running: Wait for the specified duration 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 new value is generated whenever there's a change in billing information. |
| 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. Avoid hardcoding line item counts or file sizes as they 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 based on certain criteria, such as file size or number of records, 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": "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"
}
\]
}
}
Download reconciliation line items from Azure blob storage
First, you need to obtain the shared access signature (SAS) token and the blob storage location. Find these details in the sasToken and rootDirectory properties of the manifest payload API response.
To proceed, follow these steps:
- Download the blob file using the Azure Storage SDK/tool.
- Unzip the file, which is in the JSONLines format.
Tip
Be sure to check out our sample code. It shows how to download and unzip the Azure blob file to your local database.
Standard API response statuses
You might get the following 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 input parameters provided. |
| 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 basic and full invoice reconciliation attributes
To compare the attributes returned by the billed invoice reconciliation API for the "full" or "basic" attribute sets, refer to this table. To learn more about these attributes and their meanings, see Use the reconciliation file.
| 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 |
Important
Each field or attribute name starts with an uppercase letter to maintain consistency with the file and improve readability.
Sample code
If you need assistance with migrating to this API, refer to the link that includes C# sample code.
API samples for getting billing reconciliation data from Partner Center.