Sales reports, quotas and the forecast

The Sales performance page (Sales > Sales performance) and five read operations show how an entity sells: the forecast of a period against each person's quota, the open pipeline by stage, expected-close month and owner, the win rate by owner, and the activity of each person (or agent). They read the deals and activities of the CRM; nothing here posts.

GET /v1/sales/pipeline   ?entity&owner_user_id&rate_day
GET /v1/sales/win-rate   ?entity&closed_from&closed_to&rate_day
GET /v1/sales/activity   ?entity&date_from&date_to
GET /v1/sales/forecast   ?entity&from_month&to_month&rate_day
GET /v1/sales/quotas     ?entity&year
PUT /v1/sales/quotas     {entity, quotas: [{user_id, month, amount}]}

Currencies

Every report is in the entity's functional currency. Each deal is converted on its own at one ECB fixing (rate_day, default today where the entity is; the latest fixing on or before it, named in fixing_date), rounded to the cent, and the converted amounts are added up: every grouping (by owner, by stage, by month) adds up to the same total, to the cent. Beside each converted figure the report keeps the sums in the deals' own currencies (by_currency), as recorded. A currency the ECB does not publish is listed in unconverted and left out of the converted figures (and every other currency when there is no fixing near the day); the page says so. The pipeline of the CRM keeps its amounts per currency only.

Forecast

A deal counts in the forecast of a month:

• won: in the month of its close day (closed);
• open: in the month of its expected close, in its forecast category: commit, best_case or pipeline, as its owner chose on the deal, else as its stage says (negotiation commit, proposal best case, lead and qualified pipeline). omitted leaves it out; a lost deal is never counted.

forecast is closed plus commit, best adds best case, attainment is closed of quota, gap is quota minus closed. An open deal whose expected close is before the months is late, one without a close date undated: neither is in the figures, and the page says how many there are. The forecast category changes on an open deal (PATCH /v1/opportunities/{id} with forecast_category, null for the stage's); moving a deal to won or lost ends the choice.

Quotas

A quota is what a person is to win in an entity in a month, in the entity's functional currency (one row per entity, person and month). PUT /v1/sales/quotas sets each line; a quota already set takes the new amount, audited (quota.set, with the previous amount), and 0 takes it back. A quota is never deleted, and the database keeps its person in the organization and its currency the entity's.

Win rate and activity

The win rate counts the deals won and lost in a range by owner: the rate by count and by converted value, the average deal won and the days from a won deal's creation to its close. The activity counts, per person who recorded it (created_by; an agent is a row of its own), the calls, meetings, e-mails and notes logged in the range, the tasks set, the stage moves, the tasks marked done in the range (by who did them), and the tasks assigned to each person that are open and overdue today.

Who does what

An AI assistant reads the same reports through the MCP tools sales_pipeline_report, sales_win_rate, sales_activity, sales_forecast and list_sales_quotas (MCP tools), and sees only the deals and quotas the person behind its key sees (sales teams).

Not yet

Teams and managers (a forecast rolled up by team), a manager's adjustment of a person's call, and the fiscal year as a period (the page offers calendar months, quarters and years; the API takes any months).