ReferenceId JSON Format Update in Reconciliation Files: What CSP Partners Should Check Now

Microsoft has reminded Cloud Solution Provider (CSP) direct bill partners and distributors that the ReferenceId attribute in billed and unbilled reconciliation files has moved to a structured JSON format, effective June 15, 2026.

This is a billing operations change that deserves attention even though Microsoft says pricing, charges, billing logic, and invoice totals are not impacted. The risk is not the commercial calculation. The risk is that partner systems may still assume ReferenceId is a simple string.

What changed

The ReferenceId value now uses a structured JSON format. Microsoft’s example includes fields such as osId, id, and v.

This applies to both:

- billed reconciliation files,
- unbilled reconciliation files.

Download locations and access methods remain unchanged, but the shape of the ReferenceId value has changed. Any reporting, ingestion, or reconciliation process that parses this field needs to handle the new structure.

Why it matters

The financial totals are not the issue here; the parsing assumption is.

Many partner billing workflows depend on automated processing of reconciliation files. Those workflows may feed internal reporting, customer invoice checks, margin analysis, charge validation, ERP integration, or support investigations. If a script, data pipeline, or reporting model expects ReferenceId to be a plain string, a JSON value can cause parsing failures, broken mappings, or silent data-quality issues.

Even if the file downloads successfully and totals remain correct, downstream automation may fail when it tries to transform or join on ReferenceId.

What partners should check

Partners should review every place where ReferenceId is consumed. This includes formal billing platforms and smaller operational scripts that may have been built over time.

Key checks include:

  1. Confirm ingestion pipelines can accept JSON-formatted ReferenceId values.
  2. Verify reporting tools do not flatten or escape the field incorrectly.
  3. Review joins, filters, and lookups that previously treated ReferenceId as a simple string.
  4. Test customer-facing billing reports for formatting issues.
  5. Confirm support and finance teams understand what the new structure means.
Partners should also review any validation logic that flags unexpected characters, braces, quotation marks, or nested structures in reconciliation data.

Recommended next steps

Start with a small sample of current billed and unbilled reconciliation files and run them through the same process used for production reporting. Look for parsing errors, missing values, transformation failures, or changed output in dashboards and exports.

If internal systems store ReferenceId in a fixed-width or restricted text field, verify that the new JSON structure fits without truncation. If ReferenceId is used in APIs, integrations, or customer exports, confirm that escaping is handled correctly.

Bottom line

This update should not change what customers are charged, but it can affect how partners process and explain reconciliation data. CSP partners should validate their billing automation now so the ReferenceId format change does not create avoidable operational noise.

Source: https://learn.microsoft.com/en-us/partner-center/announcements/2026-june#reminder-referenceid-format-update-in-reconciliation-files