# party_contract_values

Compare agreed contract value, billed amounts, payments and balances by counterparty and native unit. Unknown prices remain unknown; this is not recognized revenue.

## What it shows

Contract value per party, side (customer: what they agreed to pay you; vendor: what you agreed to pay them; other: any other role) and native unit: agreed, cancelled, contractValue (agreed less cancelled, kept after a contract ends) and remaining (still to perform).

A priced-rights contract's service and capacity rights count the part of their price that recurs whatever is used, as MRR does, each period at the price of the contract version in force when it began, for every period from acceptance through a fixed term; an open-ended right counts one year of its periods at the price in force at as_of, or at its end (its annualised value, 12 x MRR), or, if it ended within its first contract year, that year less the periods from the end. Remaining is the rest of the term, or of the contract year whose period started last.

Periods starting on or after the contract's end are cancelled, and so is a termination's refund of unearned time of the period the end cut short; a right billed once on acceptance counts once, and a fee billed only on cancellation or termination is not counted. A historical activity contract counts its recorded contract_flow commitments (4100 agreed, 5100 cancelled, 1100 remaining), the lines activity_balances with party_id shows. Rows are ordered by party, side (customer, vendor, other) and unit.

A requested id that names no party is listed in unknownPartyIds; a party with nothing agreed returns no rows. Get party ids from the parties read; at most 50 per call.

## Example MCP App view

The read-only example below uses illustrative demo data and the same report component as the MCP App. These are not your books or the result of the request example.

<iframe class="docs-report-preview" src="/docs/report-previews/party_contract_values.html" title="party_contract_values report view with demo data" loading="lazy" sandbox referrerpolicy="no-referrer"></iframe>

[Open the full example view](/docs/report-previews/party_contract_values.html).

## Inputs

Send the fixed `kind` and these parameters at the top level of the report request, not inside `input`. Omitting as_of uses the server's current time.

Required means required within its containing object; an optional parent can be omitted.

| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
| `party_ids` | string | Yes | One or more party ids, comma-separated, e.g. pty_a,pty_b (at most 50; spaces around commas are ignored). Example: `"pty_example"`. |
| `contract_id` | string | No | Resolved activity-contract subject ID.  |
| `as_of` | string | No | The date (YYYY-MM-DD) or UTC timestamp (RFC 3339) the report is taken at. A date is a UTC day and includes everything on it; a timestamp includes everything before that moment. A calendar date includes the whole UTC day (exclusive cutoff); an explicit timestamp keeps the stated instant. Format: moment. Example: `"2026-10-01"`. |
| `contract_value_only` | boolean | No | true returns only party/side/unit identity and contractValue, using maintained effective-time totals for list reads; cannot be combined with by_contract. valueSource describes maintained, mixed or computed fallback reads.  |
| `by_contract` | boolean | No | true splits each row by contract, adding contractId, contractName and annualised (the row holds an open-ended right's one year rather than only a committed term); the rows add up to those without it.  |

## Reading the result

Running this report does not change the books. Its description above distinguishes recorded-book summaries from previews based on supplied facts or assumptions. Interpret its totals, grouping, missing-data indicators and pagination using that description. Monetary amounts are integer strings in the reported unit; ratios and assumptions can be fractional numbers. An empty result is not evidence that the business had no activity.

The public OpenAPI contract does not enumerate this report's result fields. Fetch `GET /v1/reports` for its live description and parameters, and inspect the returned JSON rather than assuming an output shape.

## Example request


```json
{
  "kind": "party_contract_values",
  "party_ids": "pty_example",
  "as_of": "2026-10-01"
}
```


[All reports](/docs/report-reference/) · [Operation and errors](/docs/api-reference/operations/reports-run/) · [Reusable schemas](/docs/api-reference/components/)

Keep credentials out of prompts; rehearse writes only in a disposable sandbox.

## Exact request schema


```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "kind": {
      "const": "party_contract_values"
    },
    "party_ids": {
      "description": "One or more party ids, comma-separated, e.g. pty_a,pty_b (at most 50; spaces around commas are ignored).",
      "type": "string",
      "minLength": 1
    },
    "contract_id": {
      "description": "Resolved activity-contract subject ID.",
      "type": "string",
      "minLength": 1
    },
    "as_of": {
      "description": "The date (YYYY-MM-DD) or UTC timestamp (RFC 3339) the report is taken at. A date is a UTC day and includes everything on it; a timestamp includes everything before that moment.",
      "type": "string",
      "minLength": 1
    },
    "contract_value_only": {
      "description": "true returns only party/side/unit identity and contractValue, using maintained effective-time totals for list reads; cannot be combined with by_contract. valueSource describes maintained, mixed or computed fallback reads.",
      "type": "boolean"
    },
    "by_contract": {
      "description": "true splits each row by contract, adding contractId, contractName and annualised (the row holds an open-ended right's one year rather than only a committed term); the rows add up to those without it.",
      "type": "boolean"
    }
  },
  "required": [
    "kind",
    "party_ids"
  ]
}
```