Billed and unbilled daily rated usage reconciliation API v2 (GA)

Applies to: Partner Center (unavailable in Azure Government or Azure China 21Vianet.)

Our new asynchronous API offers a faster and more efficient way to access your billing and reconciliation data through Azure blobs. Instead of keeping a connection open for hours or processing batches of 2,000 line items, you can now streamline your workflow.

The new commerce daily rated usage reconciliation APIs use advanced techniques like valet key and asynchronous request-reply patterns. These APIs provide you with a shared access signature (SAS) token that you can use to access either all the attributes or a subset of the daily rated usage reconciliation data.

Our APIs use optimized techniques to boost your efficiency, so you can achieve faster results with less effort. Embrace these APIs to simplify your data access and improve your overall efficiency.

You can use these APIs for the MS Graph public/global cloud only now. They aren't yet available for Azure Government or Azure China 21Vianet.

API overview

To help you retrieve billed new commerce daily rated usage line items asynchronously, we offer two key API endpoints. Here's a streamlined guide to get you started:

Usage line-item endpoint

First, use this API to fetch new commerce daily rated usage 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.

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 is complete, 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.

By following these steps, you can efficiently manage your invoice reconciliation process.

Sequence diagram

Here's a sequence diagram that shows the steps for downloading the reconciliation data.

User action sequence

To retrieve new commerce daily rated usage reconciliation line items, follow these steps:

Step 1: Submit request

Submit a POST request to the API endpoint.

Get unbilled daily rated usage line items

Get new commerce unbilled daily rated usage line items for the current or last calendar month or billing period.

API request

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export

Accept: application/json

Content-Type: application/json

{

"currencyCode": "USD",

"billingPeriod": "current",

"attributeSet": "basic"

}

Request body

Request headers

To request headers for the API, see Reliability and support.

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 may also encounter other statuses depending on your requests. These statuses are listed in the Standard API response statuses section.

Get billed daily rated usage line items

Get new commerce billed daily rated usage line items for an invoice for the closed billing period.

API request

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export

{  
"invoiceId": "G00012345",  
"attributeSet": "full"  
}

Query parameters

N/A

Request body

Request header

Request headers for the API. To learn more, see the reliability and support.

API response

HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

When you use the API, it typically returns an HTTP 202 status. For other possible statuses based on your requests, see Statuses.

Step 2: Check request status

To keep track of a request's status, ensure you receive an HTTP 200 response 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

Request header

To request headers for the API, see Reliability and support.

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:

Response payload

The API response payload includes the following attributes:

Resource location object

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 processing data.

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 daily rated usage reconciliation line items from Azure blob storage

First, you need to get the shared access signature (SAS) token and the blob storage location. You can find these details in the "sasToken" and "rootDirectory" properties of the manifest payload API response. Then to download and unzip the blob file, use the Azure Storage SDK/tool. It's in the JSONLines format.

Standard API response statuses

You might receive these HTTP statuses from the API response:

Compare beta and GA versions

Check out the comparison table to see the differences between the beta and the generally available (GA) versions. If you're currently using the beta version, transitioning to the GA version is straightforward and easy.

Daily rated usage reconciliation line item attributes

To compare the attributes returned by the billed invoice reconciliation API for the "full" or "basic" attribute sets, refer to the following table. To learn more about these attributes, see this documentation.

Sample code

To use this API, see the following link, which includes C# sample code.

Partner Center API samples: Get billing recon data.