This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Applies to: Partner Center (unavailable in Azure Government or Azure China 21Vianet)
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:
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.
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.
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.
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.
Performance benefits
Instead of maintaining long-lived connections and processing fixed batches, the new system allows you to:
Security improvements
The valet key pattern, implemented through SAS tokens, provides:
Architectural advantages
The asynchronous request-reply pattern acts like a personal assistant who:
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.
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.
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:
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.
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.
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.
Here's a sequence diagram that shows the steps for downloading new commerce invoice reconciliation data.
Here's the user action sequence to retrieve billed invoice reconciliation data:
Submit a POST request to the API endpoint.
Get the billed invoice reconciliation line items.
POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export
Accept: application/json
Content-Type: application/json
{
"invoiceId": "G016907411",
"attributeSet": "basic"
}
N/A
| 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 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.
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. |
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.
Retrieves the status of a request.
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
| Name | Include in | Required | Type | Description |
|---|---|---|---|---|
| operationId | Request URI | True | String | A unique identifier to check the request status. Required. |
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.
N/A.
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. |
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. |
| 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". |
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
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"
}
(10 seconds after the previous request…)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
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"
}
\]
}
}
First, you need to obtain the shared access signature (SAS) token and the blob storage location (combine the root directory and blob name). Find these details in the sasToken, rootDirectory, and blobs properties of the manifest payload API response.
To proceed, follow these steps:
Tip
Be sure to check out our sample code. It shows how to download and unzip the Azure blob file to your local database.
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. |
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 how to 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.
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.
Training
Learning path
Use advance techniques in canvas apps to perform custom updates and optimization - Training
Use advance techniques in canvas apps to perform custom updates and optimization
Certification
Microsoft Certified: Dynamics 365 Finance Functional Consultant Associate - Certifications
Sie analysieren und übersetzen finanzielle Geschäftsanforderungen in Prozesse und Lösungen, die branchenspezifische empfohlene Praktiken implementieren.