> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Quote deal metrics

The commercial numbers of a quote, calculated by the engine that will invoice it: contract values, discounts against list, commitments and the breakdown per subscription, line and schedule.

---

## Why this matters

Desk shows these figures on the quote, a CRM integration writes them onto the opportunity, and an AI assistant quotes them back in a summary. Calculating them outside Solvimon means re-implementing rating: overrides, discounts, commitments, ramps and proration, each one a chance to drift from what the invoice engine actually bills.

The summary endpoint removes that duplication. It simulates the invoices of the quote's pricing plan subscriptions over their term and reports the totals, so the number on the quote and the number on the first invoice come from the same calculation.

## Read the summary

[GET /v1/quote-versions/\{id}/summary](https://docs.solvimon.com/api-docs/configuration-api/quote-versions/get-quote-versions-by-resource-id-summary) takes the quote version and returns the whole summary in one response.

**`Request`**

```bash Request
curl https://test.api.solvimon.com/v1/quote-versions/qove_8Hq2pqJnwo42rzGV7abcd/summary \
  -H "X-API-KEY: <apiKey>"
```

**`Response`**

```json Response
{
  "object_type": "QUOTE_VERSION_SUMMARY",
  "quote_version_id": "qove_8Hq2pqJnwo42rzGV7abcd",
  "computed_at": "2026-10-02T09:14:52Z",
  "currency": "EUR",
  "term": {
    "start_at": "2026-11-01T00:00:00Z",
    "end_at": "2027-11-01T00:00:00Z",
    "months": "12.00",
    "assumed": false
  },
  "tcv": { "quantity": "108000.00", "currency": "EUR" },
  "list_tcv": { "quantity": "120000.00", "currency": "EUR" },
  "acv": { "quantity": "108000.00", "currency": "EUR" },
  "contracted_arr": { "quantity": "103000.00", "currency": "EUR" },
  "contracted_arr_fully_ramped": { "quantity": "114000.00", "currency": "EUR" },
  "one_off_total": { "quantity": "5000.00", "currency": "EUR" },
  "commitment_total": { "quantity": "24000.00", "currency": "EUR" },
  "discount_total": { "quantity": "12000.00", "currency": "EUR" },
  "unallocated_discount_total": { "quantity": "0.00", "currency": "EUR" },
  "markup_total": { "quantity": "0.00", "currency": "EUR" },
  "blended_discount": {
    "amount": { "quantity": "12000.00", "currency": "EUR" },
    "percentage": "10.00"
  },
  "variable_note": "Usage-based and credit lines are priced per use, so they count as zero in the totals.",
  "pricing_plan_subscriptions": [ ... ]
}
```

Every amount is in `currency`, the billing currency of the quote's pricing plan subscriptions, and `computed_at` records when the figures were calculated. Reading the summary again recalculates it, so it always reflects the quote as it stands.

## What each metric means

| Field                         | Meaning                                                                                                                     |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `tcv`                         | Total contract value: everything invoiced over the term, net of discounts and including commitments.                        |
| `list_tcv`                    | The same total at list prices, before discounts and overrides.                                                              |
| `acv`                         | Annual contract value, summed over the pricing plan subscriptions.                                                          |
| `contracted_arr`              | Recurring contract value per year: `tcv` minus one-off fees, divided by the term in years.                                  |
| `contracted_arr_fully_ramped` | Annual recurring revenue at the end of the term, so a ramped deal is measured at the rate it finishes on.                   |
| `one_off_total`               | The one-off fees over the term.                                                                                             |
| `commitment_total`            | The commitment top-ups over the term.                                                                                       |
| `discount_total`              | The configured discounts over the term, as a positive amount, including the unallocated ones.                               |
| `unallocated_discount_total`  | The part of `discount_total` that belongs to no single line, such as a discount on the invoice total.                       |
| `markup_total`                | The configured markups over the term.                                                                                       |
| `blended_discount`            | The step from `list_tcv` to `tcv`, as an `amount` and a `percentage` with two decimals. Absent when the list value is zero. |

`estimated_usage_total` and `estimated_tcv` are reserved for a usage forecast and are not calculated yet. Treat them as absent rather than as zero.

> **Note**
>
> Usage-based lines, usage-based conversions and credit lines are priced per use, so they count as zero in every total. When a quote contains one, the response carries `variable_note` saying so, which is the text to show next to the figures.

### The term the metrics cover

`term` is the window the totals are calculated over: from the start of the first pricing plan schedule to the end of the initial term, or failing that the end of the last schedule.

| Field                | Meaning                                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------------------- |
| `start_at`, `end_at` | The bounds of the term.                                                                                       |
| `months`             | Its length in months, with two decimals.                                                                      |
| `assumed`            | `true` when a subscription has neither an initial term nor an end date, so twelve months were assumed for it. |

An `assumed` term is worth surfacing in your own UI: the contract values are real, but the period they are annualised over was a default rather than something the deal states.

## The breakdown per subscription

`pricing_plan_subscriptions` repeats every metric above per subscription, each with its own `term` and `blended_discount`, and adds two lists.

`lines` holds one entry per pricing item config, with `product_item_name`, `model_type`, `pricing_type` and the `units` the config is priced for. `list_bands` and `quoted_bands` give the price bands before and after the override and discount, so you can show list against quoted per tier. `list_total` and `quoted_total` are that line's totals over the term, and `discount` is the step between them. The flags say how to read the line: `override` when the schedule replaces the plan's pricing, `one_off` for a one-off fee, and `variable` for a line priced per use, which is the one that counts as zero. `pricing_plan_schedule_ids` names the schedules that rate the line, in the order they start.

`schedules` holds one entry per pricing plan schedule, with its `start_at` and `end_at`, its `quoted_total` and `list_total` within the term, and the `discount_total`, `markup_total`, `commitment_total` and `one_off_total` that fall inside it. Two fields are there for the commercial conversation rather than the maths: `invoice_count`, the number of regular invoices in the term excluding the final one, and `first_invoice_base_amount`, what the customer is billed before tax the first time.

Together these answer the question a ramp raises: what is this deal worth in total, and what does the customer pay on day one.

## Responses to handle

| Status | When                                                                                         | What to do                          |
| ------ | -------------------------------------------------------------------------------------------- | ----------------------------------- |
| `200`  | The summary was calculated.                                                                  | Use it.                             |
| `404`  | No summary can be calculated, for example a quote version with no pricing plan subscription. | Show nothing rather than zeros.     |
| `409`  | A change to the configuration is still being processed.                                      | Retry shortly.                      |
| `422`  | The invoice engine cannot calculate it, for example a term that spans too many invoices.     | Surface it; retrying will not help. |

The call runs the invoice engine, so it is slower than a plain read and has a 30 second timeout. Request it when a quote is opened or saved rather than on every keystroke, and cache it against `computed_at` if you render it repeatedly.

## Edge cases

* The endpoint needs the `QUOTE.VIEW` permission. An integration that only holds pricing permissions cannot read it.
* `blended_discount` and a line's `discount` are absent when the list total is zero, which happens for a quote that is entirely usage-based. Do not render a percentage in that case.
* A discount amount can be negative when a markup pushes the quoted total above list.
* The figures follow the quote version, not the quote. Read the summary of the version you are showing; an earlier version reports the deal as it was then.

---