Deals
Overview
A deal is a concrete sales opportunity: a customer, an amount, an expected close. It travels along a pipeline through consecutive stages — from first contact to won or lost.
Every stage carries a probability of closing. From that comes the weighted value: amount times probability. That single figure is why a pipeline says more than a list — it distinguishes between "we have a lot in progress" and "we will close a lot".
Core tasks
Create and run a deal. A deal carries title, customer, contact, value, probability, stage, forecast category, expected close, owner, notes and labels.
Capture recurring revenue. Alongside the one-off value there is MRR — monthly recurring revenue. The annual figure ARR derives from it as MRR × 12 and is not maintained separately. For subscriptions the one-off value is the wrong number; hence both exist.
Set the forecast category. Alongside the calculated probability sits the human judgement: Pipeline, Best case, Commit or Worst case. The two together produce a more dependable forecast than probability alone could deliver.
Close. Won completes the deal. Lost requires a loss reason — deliberately: a loss without a reason is a lost insight. The reasons are evaluated under Funnel & analysis.
Create what follows. From a deal you can create a quote, project, contract or licence — depending on which modules are active. The transition from selling to delivering is therefore one click, not a break in the chain.
Keep the overview. The list shows title, stage, value, probability, weighted value, owner and close date; filtering is by customer and owner, grouping by stage, owner or forecast. The header carries weighted, unweighted and best case.
Fields in detail
The What it does column answers what changes in the system — not what the field is called. The grey name behind the label is the API field: the same thing runs under that name through automation, import and AI tools.
Creating and editing a deal
| Field | Required | Values / format | What it does |
|---|---|---|---|
Title title | yes | text, max. 500 characters | The only required entry. Carries the deal through list, board, forecast and history; on "won" it becomes the name of the follow-up object. |
Customer customerId | no | an existing customer | Who the deal belongs to. Only with a customer set can a contact be picked, and only then does the deal appear on the customer record. |
Contact primaryContactId | no | a contact of the chosen customer | The person you negotiate with. Quotes and mails sent from the deal go to them. Without a customer the field stays locked. |
Pipeline pipelineId | no | a pipeline of type "deal" | The sales path the deal runs on. Determines the selectable stages and the columns of the board. |
Stage stageId | no | a stage of the chosen pipeline | Where the deal stands. On a move the deal adopts the default probability of the target stage if one is set. The stage type also decides whether the deal counts as open, won or lost. |
Value valueAmount | no | amount, 0 or greater | The one-off order volume. The basis for pipeline total, weighted value and forecast. |
MRR (monthly) mrrAmount | no | amount, 0 or greater | Recurring monthly revenue, kept apart from the one-off value. It is not added into the value but reported on its own. |
Recurring amount recurringAmount | no | amount, 0 or greater | The recurring revenue per billing cycle — the figure you actually agree on. With monthly billing it equals the MRR, with yearly billing it is the annual amount. Without it the MRR stands. |
Billing frequency billingFrequency | no | monthly, quarterly, semi-annual, yearly | The rhythm the recurring amount is charged in. Only it turns the amount into a comparable monthly figure. |
Term (cycles) contractCycles | no | 1 to 600 | How many billing cycles the agreement runs — not months: six cycles with quarterly billing is one and a half years. Empty = open-ended. |
Instalments installmentCount | no | 2 to 120 | How many instalments the one-off value is meant to be split into. This is the intent; the instalment plan with real due dates is created on the document, not on the deal. |
Probability (%) probability | no | whole number 0–100 | How likely the close is. Multiplied by the value it yields the weighted value the forecast works with. A stage change overwrites it if the target stage has a default. |
Expected close expectedCloseDate | no | date | When the deal is meant to land. Decides which forecast period it counts in; without a date it stays out of every period report. |
Forecast forecastCategory | no | Pipeline, Best case, Commit, Worst case | The judgement alongside the probability. The forecast shows the four buckets separately — "Commit" is what you are willing to stand behind. |
Owner ownerId | no | an employee | Who runs the deal. Governs visibility with crm.deal.view (without view_all you only see your own) and the attribution in forecast and goals. |
Notes notes | no | multi-line text | Free text on the deal. It does not replace the communication history. |
Tags tags | no | several terms | Free grouping across pipeline and stage; filterable and usable as an entry into marketing journeys. |
Participants participants | no | contacts with role and note | Who decides on the customer side — decision maker, economic buyer, champion, technical, user, blocker. A deal is rarely won with a single person; this is where you keep who else you have to convince. Saving replaces the whole list. |
Watchers watcherIds | no | list of users | Who may read along without running the deal. It only matters once visibility is set to "own only" — and it replaces no permission: without crm.deal.view in the brand a watcher sees nothing either. Saving replaces the whole list. |
Marking as lost or won
| Field | Required | Values / format | What it does |
|---|---|---|---|
Lost reason lostReasonId | yes when losing | master data "Lost reasons" | Why the deal did not land. Required, so the loss report is not made of empty reasons; maintained under CRM settings. |
Follow-up object followUpType | yes when winning | quote, project, contract, licence | What the won deal becomes. Customer, contact, value and title are carried over instead of retyped. |
Interface and automation only
| Field | Values / format | What it does |
|---|---|---|
sourceId | master data "Sources" | Where the deal came from. Converting a lead carries it over; the deal mask has no field of its own for it. |
brandId | one of your brands | Brand of the deal. Comes from the lead or the customer; whoever cannot see the brand cannot see the deal. |
externalRefs | label-to-value mapping | Origin in a foreign system — the identifier under which the same deal is kept there. A second import recognises it by that. |
List: columns, filters and grouping
| Column | From | What it shows |
|---|---|---|
| Title | title | Name of the deal. |
| Stage | stageId | Changeable in the row; that moves the deal along the pipeline. |
| Value | valueAmount | One-off volume, sortable. |
| Prob. | probability | Closing probability in percent. |
| Weighted | valueAmount × probability | The figure the forecast works with. |
| Owner | ownerId | Changeable in the row. |
| Close | expectedCloseDate | Expected closing date. |
Filtering is by customer and owner, grouping by stage, owner or forecast. The header shows the pipeline total weighted, unweighted and as a best case.
Settings & permissions
- Module
module.crm. - Two levels of visibility:
crm.deal.viewfor your own,crm.deal.view_allfor everyone's.
Plus crm.deal.edit, crm.deal.delete and crm.deal.assign for moving ownership.
- Pipelines, stages and loss reasons are maintained under CRM settings; the
probability hangs off the stage.
- A deal is not a document. It records the opportunity; the invoice arises from the quote.
FAQ & troubleshooting
The weighted value does not match my expectation. It follows the stage's probability, not your judgement. Your judgement is the forecast category — the two are deliberately separate.
ARR cannot be entered. Correct: ARR is calculated (MRR × 12). Maintain the MRR.
I cannot mark a deal as lost. A loss reason is required. If the selection is empty altogether, no reasons have been set up under CRM settings yet.
The deal does not appear in the forecast. Open deals with an expected close date appear there. Without a date it is missing — the most common cause of a forecast that looks too low.