Get invoice billed commercial consumption line items

Article
03/12/2024

Note

This API won’t stop working after September 30, 2024. It will still be available and functional for your past billed daily rated usage line items. 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 billed daily rated usage line items for invoices that are created for billing periods between September 2022 to September 2024.
Use only this API to get billed daily rated usage line items for invoices that were created for billing periods prior to September 2022.
Use only API v2 GA to get billed daily rated usage line items for invoices that were created for billing periods from September 2022.

To start preparing for the migration to the new APIs, see the following link:

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

You can use the following methods to get a collection of details for commercial consumption invoice line items (also known as closed daily rated usage line items) for a specified invoice.

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

Prerequisites

Credentials as described in Partner Center authentication. This scenario supports authentication with both standalone App and App+User credentials.
An invoice identifier. This identifies the invoice for which to retrieve the line items.

C#

To get the commercial line items for the specified invoice, you must retrieve the invoice object:

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 billed detail information (for example, onetime). The InvoiceLineItemType specifies the type (for example, UsageLineItem).

The following example code uses a foreach loop to process the line items 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 invoiceId;
// 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(invoiceId).By("onetime", "usagelineitems", curencyCode, period, pageMaxSizeReconLineItems).Get();

var fetchNext = true;

ConsoleKeyInfo keyInfo;

var itemNumber = 1;
while (fetchNext)
{
    Console.Out.WriteLine("\tLine line 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(invoiceId).By("onetime", "usagelineitems", curencyCode, period, pageMaxSizeReconLineItems).Seek(seekBasedResourceCollection.ContinuationToken, SeekOperation.Next);
        }
    }
}

For a similar example, see the following:

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

REST request

Request syntax

Use the first syntax to return a full list of every line item for the given invoice. For large invoices, use the second syntax with a specified size and 0-based offset to return a paged list of line items. Use the third syntax to get the next page of recon line items using seekOperation = "Next".

Method	Request URI
GET	{baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode={currencycode} HTTP/1.1
GET	{baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode={currencycode}&size={size} HTTP/1.1
GET	{baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode={currencycode}&size={size}&seekOperation=Next

URI parameters

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

Name	Type	Required	Description
invoice-id	string	Yes	A string that identifies the invoice.
provider	string	Yes	The provider: "OneTime".
invoice-line-item-type	string	Yes	The type of invoice detail: "UsageLineItems".
currencyCode	string	Yes	The currency code for the billed line items.
period	string	Yes	The period for billed recon. example: current, previous.
size	number	No	The maximum number of items to return. Default size is 2000
seekOperation	string	No	Set seekOperation=Next to get the next page of recon 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. 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.

REST examples

Request-response example 1

The details for this example REST request and response are as follows:

Provider: OneTime
InvoiceLineItemType: UsageLineItems
Period: Previous

Request example 1

GET https://api.partnercenter.microsoft.com/v1/invoices/T000001234/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