Knowledge Base

API Guide for Billing Integration (5.0)

Overview

This document provides an overview of the billing integration process between Cloudmore 5.0 and ERP or financial systems.

Billing integration is the most common use case on Cloudmore and is generally straightforward, often requiring only a single API call to retrieve the necessary data.

While billing is generated monthly, the exact dates vary by service. Microsoft NCE data is available between the 6th and 8th of each month, while legacy Microsoft services follow different partner-specific schedules. For most organizations, retrieving billing data once or twice a month is sufficient.

This document outlines the available Cloudmore API endpoints for exporting billing data. For complete technical details, refer to the Cloudmore Swagger documentation.

Available API Calls

API Endpoint

Data Returned

Note

.../billing/reports/BillingLineDetails

All services

Recommended API call. Detailed, paginated billing lines returned synchronously.

.../billing/reports/BillingTotalAll
.../billing/reports/BillingTotalByDate
.../billing/reports/BillingTotalByService
.../billing/reports/BillingTotalByOrganization
.../billing/reports/BillingTotalByOrganizationService
.../billing/reports/BillingTotalBySubscription
.../billing/reports/BillingTotalByCostCenter

All services (aggregated)

Pre-aggregated billing totals at different levels.

.../billing/azurereports/AzureOneTimeInvoice/

Microsoft Data: 365 NCE, Azure NCE, Perpetual Licenses, Software Subscriptions, Marketplace Items, Reserved Instances

Returns detailed Microsoft information for all NCE services.

.../billing/cspreports/MonthlyBillingPerOrganization

Microsoft O365 Legacy

Detailed report for Microsoft Legacy services (Recurring invoice).

.../billing/azurereports/InvoiceOverview

Microsoft Azure Legacy billing data

Detailed report for Microsoft Legacy Azure services.

.../billing/azureonetimeusage/AzureOneTimeInvoice

Microsoft Azure Usage data

Note: usage report may slightly differ from the billing report due to Microsoft rounding and transformations.

Legacy APIs

API Endpoint

Note

.../billing/reports/MonthlyBillingPerOrganizationAsync

Replaced by BillingLineDetails. Retained for backward compatibility only.

.../billing/reports/MonthlyBillingPerOrganization and .../MonthlyBillingPerService

Legacy. Should only be used for testing. Not for production.

Recommendation

Cloudmore strongly advises using the .../billing/reports/BillingLineDetails endpoint to access billing information. This endpoint provides comprehensive billing data across all services, is returned synchronously with pagination, and is designed to be future-proof. Using this API avoids the need to update your billing integration when expanding from Microsoft services to other offerings.

If only summarized totals are needed (per organization, service, subscription, date, or cost center), the corresponding BillingTotal* aggregated API can be used.

Pre-Generated Billing Reports

Common Conventions

Aspect

Detail

Swagger Heading

PreGeneratedBillingReports

Base path

/api/resellers/{resellerId}/billing/reports/{Action}

Method

GET

Produces

application/json

resellerId

Path parameter, GUID

Date period

startDate and endDate are both inclusive

Currency

If convertToCurrency is omitted, amounts are returned in the default sales/cost currency. If supplied, it must be a valid 3-letter ISO 4217 code.

Filtering

organizationIds, organizationGroupIds, and serviceIds are optional and repeatable; omitting a filter returns all

averageMarginPercentage

Calculated as (SUM(totalSales) - SUM(totalCost)) / SUM(totalSales) * 100

Pagination

  • Request - Send the optional pageToken HTTP header to fetch a specific page; omit it for the first page.

  • Response - When more pages exist, a nextPageToken HTTP header is returned. Pass its value in the next request's pageToken header. No nextPageToken header means it's the last page.

  • Page size is fixed at 1000 items. BillingTotalAll is not paginated.

Example Request with Token

curl -i --location \
  'https://api.cloudmore.com/api/resellers/3f9a2c14-7b6e-4d81-a5c3-1e8f90d4a72b/billing/reports/BillingLineDetails?startDate=2026-01-01&endDate=2026-01-31&organizationIds=b21d7e4a-9c05-4f3e-8a16-2d7c6e94f018&splitByCostCenter=true' \
  --header 'pageToken: d3f6a81b-4e29-4c07-9a52-6f81b0e3c7a4|2026-01-06T00:00:00.0000000Z' \
  --header 'Authorization: Bearer {token}'

Status Codes

Status

Meaning

200 OK

Success. Paginated endpoints may include a nextPageToken response header.

400 Bad Request

Missing/invalid parameters; invalid convertToCurrency; startDate later than endDate.

401 Unauthorized

Missing or invalid authentication credentials.

403 Forbidden

Authenticated, but the account lacks permission for this reseller.

404 Not Found

Reseller, organization, organization group, or service not found.

Azure Service Name Mapping

A serviceId is normally associated with a single serviceName. Azure billing is broken down by model type, so a single Azure serviceId can appear under several serviceNames for the following APIs: BillingTotalByService, BillingTotalByOrganizationService, and BillingTotalBySubscription.

Service Name

Azure Consumption

Microsoft Azure & Software

Azure Marketplace

Azure Reserved Instances

Azure Perpetual Software

Azure Software Subscriptions

Azure Savings Plan

API Details

Detailed documentation for each API endpoint is available in the child pages:

  • Billing Line Details API Details - GET /api/resellers/{resellerId}/billing/reports/BillingLineDetails

  • Aggregated Billing Total API Details - All BillingTotal* aggregated endpoints