---
title: "Customer MRR movements history (accountant mirror)"
method: GET
path: "/accountant/companies/{customerId}/metrics/mrr-movements"
tags: ["Overview"]
---

# Customer MRR movements history (accountant mirror)

`GET /accountant/companies/{customerId}/metrics/mrr-movements`

## Request

- Base URL: `https://api.medianfi.com/api/v1`
- URL: `https://api.medianfi.com/api/v1/accountant/companies/{customerId}/metrics/mrr-movements`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Accountant-scoped mirror of `GET /companies/{companyId}/metrics/mrr-movements`. Unlike the customer mount, `entityId` is optional here — it defaults to the customer's single concrete entity. Entity scope is resolved from the customer's own entity roster (accountants hold no per-user entity grants): an explicit `entityId` must be one of the customer's concrete (non-group) entities; absent, the customer's single concrete entity is used; a multi-entity customer without `entityId` gets 422 ENTITY_SELECTION_REQUIRED and a customer with no entity gets 422 ENTITY_SCOPE_UNAVAILABLE.

## Query parameters

- `entityId` string, uuid
- `months` integer

## Response `200`

MRR movements envelope (same shape as the customer mount)

- MrrMovementsResponse
  - `success` true, required
  - `data` MrrMovementsData, required
    - `companyId` string, uuid, required
    - `entityId` string, uuid, required
    - `enabled` boolean, required: home_saas_metrics rollout flag for this company.
    - `available` boolean, required: True when snapshots exist and have one authoritative billing currency.
    - `unavailableReason` 'mixed_currency' | 'currency_unavailable': Why persisted history cannot be presented without misstating currency.
    - `currency` string, nullable, required: Authoritative ISO billing currency, or null when unavailable.
    - `minorUnitExponent` integer, nullable, required: Exact minor-unit scale for every amount in the response.
    - `asOf` string, nullable, required: Last completed calendar month included (YYYY-MM) — the current partial month is excluded from every window before slicing. Null when unavailable.
    - `period` object, required: Resolved completed-month window actually returned.
      - `requestedMonths` integer, required
      - `startMonth` string, nullable, required
      - `endMonth` string, nullable, required
      - `monthKeys` string[], required
    - `historyCompleteFrom` string, nullable, required: Persisted full-census coverage start (YYYY-MM) — stored authority, never inferred from observed events. Null when any expected source lacks full-census coverage.
    - `reason` 'source_not_authorized' | 'entity_access_required' | 'syncing' | 'stale' | 'failed' | 'mixed_currency' | 'insufficient_history' | 'incomplete_provenance': Customer-safe availability reason; present only when available:false.
    - `months` MrrMovementMonth[], required: Ascending by month; at most the requested window.
      - `month` string, required
      - `currentMrrMinorUnits` string, required: Exact ending MRR in authoritative minor units.
      - `newMrrMinorUnits` string, required
      - `expansionMrrMinorUnits` string, required
      - `reactivationMrrMinorUnits` string, required
      - `contractionMrrMinorUnits` string, required: Non-negative contraction magnitude.
      - `churnedMrrMinorUnits` string, required: Non-negative churn magnitude.
      - `netNewMrrMinorUnits` string, required: new + expansion + reactivation - contraction - churned.
      - `activeCustomerCount` integer: Paying customers at the end of the month (as of today on the in-progress row).
      - `excludedNonUsd` object[]: Reconstructed months only: non-USD lines excluded from this month's MRR, per currency, with their monthly amount in that currency's minor units.
        - `currency` string, required
        - `lineCount` integer, required
        - `monthlyMinorUnits` integer, required
      - `uncollectibleRenewalMrr` object: Reconstructed months only: the MRR, and how many subscriptions carry it, from renewal invoices marked uncollectible. They still count as MRR (past-due renewals keep MRR until the subscription ends); paused collection can hide behind them.
        - `subscriptionCount` integer, required
        - `mrrMinorUnits` string, required
    - `coverageGaps` string[]: Present only when reconstructed invoice history is activated for the entity: completed months (YYYY-MM) inside the window that no source covers. They are absent from months, never shown as zero.
    - `historyRefusal` 'seam_unverified' | 'seam_discontinuity': Present only when an activated reconstruction was refused; the answer is then unavailable.
    - `labelledGaps` object[]: Present only when reconstructed history is activated: months between the last rebuilt month and the first live month, shown as labelled gaps. They are absent from months, never shown as zero.
      - `month` string, required
      - `label` 'between_history_and_live', required
    - `seam` object: Present only when reconstructed history is activated: the seam between rebuilt and live months. A difference within 1% of the last rebuilt close is served as a labelled method-change adjustment (live opening minus rebuilt close, signed minor units); gap means labelled gaps separate the rebuilt and live months, so there is no continuity to check.
      - `month` string, required
      - `status` 'continuous' | 'method_change' | 'gap', required
      - `label` 'method_change'
      - `adjustmentMinorUnits` string

## Other responses

- `401`: Authentication required
- `403`: Insufficient permissions or not a company member
- `404`: Unknown customer or an explicit entityId not belonging to the customer
- `422`: Request failed validation

---

[API](https://skmtc.dev/medianfi/apis/median-api.md) · [All operations](https://skmtc.dev/medianfi/apis/median-api/llms.txt) · [OpenAPI document](https://skmtc.dev/medianfi/apis/median-api/revisions/20090ea32b0d?raw)