Get invoice unbilled commercial consumption line items

Article
03/13/2024

Note

This API will stop working after September 30, 2024. Refer to the following details to decide which version to use and when.

Unless you've switched to v2 GA, use this API until September 30, 2024, to get unbilled daily rated usage line items for current and previous billing periods.
Use only API v2 GA after September 30, 2024, to get unbilled daily rated usage line items for current and previous billing periods.

To start preparing for the migration to the API v2, see the following link:

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

How to get a collection of unbilled commercial consumption line item details.

You can use the following methods to get a collection of details unbilled commercial consumption line items (also known as open usage line items) programmatically.

Important

The daily rated usage data doesn't include the charges for these products:

Azure reservation
Azure savings plan
Office
Dynamics
Microsoft Power Apps
Perpetual software
Software subscription
Third-party SaaS product

Note

You can retrieve your daily unbilled usage data through the API or Partner Center portal. It can take up to 24 hours for the data to become available. However, there might be further delays depending on your location and when the meters report the usage.

Sometimes, you might not see the most recent unbilled usage data until the billed usage data for the previous month is delivered. This is done to ensure that billed usage data is delivered within the agreed time. Once you receive the billed usage data, you should be able to retrieve all the updated unbilled usage data from the start of the month.

Prerequisites

Credentials as described in Partner Center authentication. This scenario supports authentication with both standalone App and App+User credentials.

C#

To get the line items for the specified invoice:

Call the ById method to get an interface to invoice operations for the specified invoice.
Call the Get or GetAsync method to retrieve the invoice object.

The invoice object contains all of the information for the specified invoice. The Provider identifies the source of the unbilled detail information (for example, OneTime). The InvoiceLineItemType specifies the type (for example, UsageLineItem).

The following example code uses a foreach loop to process the InvoiceLineItems collection. A separate collection of line items is retrieved for each InvoiceLineItemType.

To get a collection of line items that correspond to an InvoiceDetail instance:

Pass the instance's BillingProvider and InvoiceLineItemType to the By method.
Call the Get or GetAsync method to retrieve the associated line items.
Create an enumerator to traverse the collection as shown in the following example.

// IAggregatePartner partnerOperations;
// string curencyCode;
// string period;
// int pageMaxSizeReconLineItems = 2000;

// all the operations executed on this partner operation instance will share the same correlation Id but will differ in request Id
IPartner scopedPartnerOperations = partnerOperations.With(RequestContextFactory.Instance.Create(Guid.NewGuid()));

var seekBasedResourceCollection = scopedPartnerOperations.Invoices.ById("unbilled").By("onetime", "usagelineitems", curencyCode, period, pageMaxSizeReconLineItems).Get();

var fetchNext = true;

ConsoleKeyInfo keyInfo;

var itemNumber = 1;
while (fetchNext)
{
    Console.Out.WriteLine("\tLine items count: " + seekBasedResourceCollection.Items.Count());

    seekBasedResourceCollection.Items.ToList().ForEach(item =>
    {
        // Instance of type DailyRatedUsageLineItem
        if (item is DailyRatedUsageLineItem)
        {
            Type t = typeof(DailyRatedUsageLineItem);
            PropertyInfo[] properties = t.GetProperties();

            foreach (PropertyInfo property in properties)
            {
                // Insert code here to work with the line item properties
            }
        }
        itemNumber++;
    });

    Console.Out.WriteLine("\tPress any key to fetch next data. Press the Escape (Esc) key to quit: \n");
    keyInfo = Console.ReadKey();

    if (keyInfo.Key == ConsoleKey.Escape)
    {
        break;
    }

    fetchNext = !string.IsNullOrWhiteSpace(seekBasedResourceCollection.ContinuationToken);

    if (fetchNext)
    {
        if (seekBasedResourceCollection.Links.Next.Headers != null && seekBasedResourceCollection.Links.Next.Headers.Any())
        {
            seekBasedResourceCollection = scopedPartnerOperations.Invoices.ById("unbilled").By("onetime", "usagelineitems", curencyCode, period, pageMaxSizeReconLineItems).Seek(seekBasedResourceCollection.ContinuationToken, SeekOperation.Next);
        }
    }
}

For a similar example, see:

Sample: Console test app
Project: Partner Center SDK Samples
Class: GetUnBilledConsumptionReconLineItemsPaging.cs

REST request

Request syntax

You can use the following syntaxes for your REST request, depending on your use case. For more information, see the descriptions for each syntax.

Method	Request URI	Description of syntax use case
GET	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode={currencycode}&period={period} HTTP/1.1	Use this syntax to return a full list of every line item for the given invoice.
GET	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode={currencycode}&period={period}&size={size} HTTP/1.1	Use this syntax for large invoices. Use this syntax with a specified size and 0-based offset to return a paged list of line items.
GET	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode={currencycode}&period={period}&size={size}&seekOperation=Next	Use this syntax to get the next page of reconciliation line items using `seekOperation = "Next"`.

URI parameters

Use the following URI and query parameters when creating the request.

Name	Type	Required	Description
provider	string	Yes	The provider: "OneTime".
invoice-line-item-type	string	Yes	The type of invoice detail: "UsageLineItems", "UsageLineItems".
currencyCode	string	Yes	The currency code for the unbilled line items.
period	string	Yes	The period for unbilled recon (for example: current, previous). Suppose you need to query your unbilled usage data of the billing cycle (01/01/2020 – 01/31/2020) in January, choose period as "Current," else "Previous."
size	number	No	The maximum number of items to return. The default size is 2000.
seekOperation	string	No	Set `seekOperation=Next` to get the next page of reconciliation line items.

Request headers

For more information, see Partner Center REST headers.

Request body

None.

REST response

If successful, the response contains the collection of line item details.

For the line item ChargeType, the value Purchase is mapped to New and the value Refund is mapped to Cancel.

Response success and error codes

Each response comes with an HTTP status code that indicates success or failure and additional debugging information. Use a network trace tool to read this code, error type, and additional parameters. For the full list, see Partner Center REST error codes.

Request-response examples

Request-response example 1

The following details apply to this example:

Provider: OneTime
InvoiceLineItemType: UsageLineItems
Period: Previous

Request example 1

GET https://api.partnercenter.microsoft.com/v1//invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode=usd&period=previous&size=2000 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 1234ecb8-37af-45f4-a1a1-358de3ca2b9e
MS-CorrelationId: 5e612512-4345-4bb0-866e-47aeda031234
X-Locale: en-US
MS-PartnerCenter-Application: Partner Center .NET SDK Samples
Host: api.partnercenter.microsoft.com