Announcement: Key details about new API endpoints for billed and unbilled usage reports

Detailed summary of the new endpoint names, validations and responses.

To align with Microsoft’s migration to new APIs for managing billed and unbilled Azure consumption line items, Cloudmore is updating our API infrastructure. Current endpoints for retrieving Azure usage reports will be deprecated. New endpoints will be introduced, and Brokers must update their integrations by January 21, 2025 to avoid disruptions.

---

What’s Changing?

• New Endpoints for Azure Usage Reports
  New endpoints will support billed and unbilled usage data retrieval. These updates ensure accurate, timely data aligned with Microsoft’s new API frameworks.

• Key Adjustments

  • Replaced usageDate with usageStartDate and usageEndDate for aggregated billed usage data.

  • Pagination requirements for data retrieval endpoints.

  • Enhanced validation for error handling and improved responses.

---

New API Endpoints and Details

1. Get Billed Azure Usage Report

Endpoint:
GET api/resellers/{resellerId:guid}/billing/azureonetimeusage/report/billed/invoice/{invoiceId:string}?pageNumber={pageNumber:int}&pageSize={pageSize:int}

Validations:

• Valid reseller ID and invoice number.

• pageNumber ≥ 1 and pageSize ≤ 500.

Response:
Includes usage line items, usageStartDate, and usageEndDate. Returns:

• 200 OK with usage line items including paging details.

• 404 Not Found if no data exists.

• 400 Bad Request for validation errors.

• 500 Internal Server Error for system failures.

Response example:

"pageNumber": int,
"pageSize":int,
"count": int,
"totalCount":int,
"usageLineItems": [
{
    "partnerId": "string",
    "partnerName": "string",
    "customerId": "string",
    "customerName": "string",
    "customerDomainName": "string",
    "invoiceNumber": "string",
    "productId": "string",
    "skuId": "string",
    "availabilityId": "string",
    "skuName": "string",
    "productName": "string",
    "publisherName": "string",
    "publisherId": "string",
    "subscriptionId": "string",
    "subscriptionDescription": "string",
    "chargeStartDate": "date-time",
    "chargeEndDate": "date-time",
    "usageStartDate": "date-time",
    "usageEndDate": "date-time",
    "meterType": "string",
    "meterCategory": "string",
    "meterId": "string",
    "meterSubCategory": "string",
    "meterName": "string",
    "meterRegion": "string",
    "unitOfMeasure": "string",
    "resourceLocation": "string",
    "consumedService": "string",
    "resourceGroup": "string",
    "resourceUri": "string",
    "tags": "string",
    "additionalInfo": "string",
    "serviceInfo1": "string",
    "serviceInfo2": "string",
    "customerCountry": "string",
    "mpnId": "string",
    "resellerMpnId": "string",
    "chargeType": "string",
    "unitPrice": "number(decimal)",
    "quantity": "number(decimal)",
    "unitType": "string",
    "billingPreTaxTotal": "number(decimal)",
    "billingCurrency": "string",
    "pricingPreTaxTotal": "number(decimal)",
    "pricingCurrency": "string",
    "entitlementId": "string",
    "entitlementDescription": "string",
    "pcToBCExchangeRate": "number(decimal)",
    "pcToBCExchangeRateDate": "date-time",
    "effectiveUnitPrice": "number(decimal)",
    "rateOfPartnerEarnedCredit": "number(decimal)",
    "invoiceLineItemType": "string" (Enum:[ None, UsageLineItems, BillingLineItems ]),
    "billingProvider": "string" (Enum:[ None, Office, Azure, OneTime, Marketplace, All ]),
    "costPricePerUnit": "number(decimal)",
    "salesPricePerUnit": "number(decimal)",
    "totalCostPrice": "number(decimal)",
    "totalSalesPrice": "number(decimal)"
  }
]

---

2. Get Unbilled Azure Usage Report

Given the asynchronous nature of the new API, you’ll need to make several API calls to get the report.

Step 1: Request unbilled usage report

Endpoint:
POST api/resellers/{resellerId:guid}/billing/azureonetimeusage/report/unbilled/period/{period:string}/export

Validations:

• Valid reseller ID and period (current or last).

Response example:

"operationId": string - returned operation id from GRPC service which will be used in subsequent API calls

Step 2: Check report status

Endpoint:
GET api/resellers/{resellerId:guid}/billing/azureonetimeusage/report/unbilled/period/{period:string}/operation/{operationId:string}/status

Validations:

• Valid reseller ID and period (current or last).

• Should be a valid GUID operation id

Response:
Represents the latest status of the report operation. Returns:

• 200 OK with operation status.

  • Status: Completed, InProgress, or Failed.

  • Includes error details for failed operations.

  • Includes Retry-After response header, to indicate next retry time in minutes.

• 400 Bad Request for validation errors.

• 404 Not Found if operation status not exists.

• 500 Internal Server Error for system failures.

• 410 Goneif the operation is expired.

Response example:

"operationId": string,
"status":string - [Enum - Completed,InProgress,Failed],
"errorMessage":string - this will be null always in successful operation, only populated when there is a failure.

Step 3: Download the unbilled usage report

Once the status is ‘Completed’, the report becomes available.

Endpoint:
GET api/resellers/{resellerId:guid}/billing/azureonetimeusage/report/unbilled/period/{period:string}/operation/{operationId:string}/result?pageNumber={pageNumber:int}&pageSize={pageSize:int}

Validations:

• Valid reseller ID, operation ID, and period (current or last).

• pageNumber ≥ 1 and pageSize ≤ 500.

Response:
Includes unbilled usage line items with paging details. Returns:

• 200 OK with unbilled usage line items.

• 400 Bad Request for validation errors.

• 404 Not Found if unbilled usage data not available or operation in progress.

• 500 Internal Server Error for system failures.

Response example:

---

How to Prepare

1. Update your API integrations
   Replace deprecated endpoints with the new ones.
   Once released, you will find detailed specifications in our Knowledge Base: API Documentation.

2. Test your implementation
   Ensure compatibility by validating responses and handling errors as described.

3. Complete updates by January 21, 2025
   The date is aligned with Microsoft’s API migration date. After this date, deprecated endpoints will no longer function.

---

Need Assistance?

For questions or support, contact our team at support@cloudmore.com. Refer to our release notes and platform updates for additional information.