Billed invoice reconciliation API v2 (GA)

Applies to: Partner Center (unavailable in sovereign cloud)

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, reduce the server load, and improve data processing times.

The new commerce billed invoice reconciliation API uses advanced techniques like valet key and asynchronous request-reply patterns. The valet key pattern allows for secure access to resources without sharing credentials, while the asynchronous request-reply pattern enables efficient communication between systems.

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. This token enhances security by granting limited time access and offers flexibility in managing data access permissions.

By adopting our optimized APIs, you can achieve faster results with less effort, simplify your data access, and improve overall efficiency. Embrace these tools to streamline your workflow and manage permissions more effectively.

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.

Important

To allow your app access to 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 Entra Admin center. Here's how:

• Register your app on the Microsoft Entra home page under the App registrations section.
• To grant the necessary permission, go to the Microsoft Entra App page. Under the API permissions section, select "Add a permission" and choose the "PartnerBilling.Read.All" scope.

By completing these steps, you ensure that your app has the required access to partner billing data.

API overview

To help you retrieve billed new commerce invoice reconciliation line items asynchronously, we offer two key API endpoints. Follow this streamlined guide to get started quickly and efficiently!

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.

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 new commerce invoice 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. 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 may 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.

Step 2: Check 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"

            }

        \]

    }

}

Step 3: Download billed invoice 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.

Tip

Make sure to check out our sample code. It shows you how to download and unzip the Azure blob file to your local database.

Standard API response statuses

You might get these 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.

Billed invoice reconciliation line item 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 this guide.

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

Make note of these changes when moving from API v1 to v2.

• Each attribute name now starts with an uppercase letter to maintain consistency with the file and improve readability.

Sample code

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

Partner-Center-Billing-Recon-Samples: Samples for API for getting Billing recon data from Partner Center (github.com).