Deal
A deal is the same thing as an opportunity: one piece of business with a value and a stage. There is one record and two words for it. *Opportunity* is the name in the data model, the API and this glossary; *deal* is what the screens and the sheets say, because that is what people say out loud.
Why two words survive in one product#
A vocabulary that insists on one word everywhere sounds tidy and reads badly. Nobody rings a colleague to ask how the opportunity went. The register a business uses among itself is *deal*, and a screen that refuses it makes the software feel like a form to fill in rather than a record of what happened.
The other direction has its own cost. *Deal* is ambiguous in English — a bargain, a discount, an arrangement — and an identifier called deal in an API invites a client author to guess which. So the boundary is drawn by audience rather than by preference.
| Surface | Word used | Why |
|---|---|---|
| The pipeline screen and the deals sheet | Deal | The register a business speaks in |
| Follow-up reasons written by the engine | Deal | They are read by a person, in a list of other reasons |
| The data model and the public API | Opportunity | One unambiguous identifier per record type |
| This glossary and the manual's own prose | Opportunity | The canonical term, so a definition has one home |
What a deal is not, in each of its other English senses#
- Not a discount
- Connect documents no prices, discounts or offers anywhere, and neither does this manual. A page that says *deal* is always talking about the pipeline record.
- Not a contract
- A signed agreement is a document. It can be attached to the record as a file, and the record is still what tracks the state of the business.
- Not a quote
- A priced proposal is one artefact sent during the *proposal sent* stage. One deal often accumulates several.
- Not an order
- Fulfilment is not modelled here. Winning a deal moves the person to *client* and, if the workspace uses it, into onboarding — it does not create a shipment.
Reading a page that uses both words#
When a page in this manual mixes them, the rule is that the sentence about what appears on a screen uses the screen's word and the sentence about what is stored uses the model's. "The deal moved to Negotiating" and "the opportunity's stage is negotiation" describe one event.
If you are writing against the API, ignore the everyday word entirely. Field names, stage identifiers and the shapes returned are documented in the public data model, and stability rules apply to those identifiers rather than to the labels a screen shows beside them. A label can be reworded in a release; an identifier is a contract.
Questions#
Is there any behaviour that differs between a deal and an opportunity?
None. There is one record, one set of stages and one history. Anything a page says about an opportunity is true of the deal you are looking at on the pipeline.
Which word should I use when asking the Connect Assistant?
Either. The Assistant's tools are named for opportunities and it understands the everyday word, so asking about deals in a stage returns the same records as asking about opportunities.
Why does the data grid call the sheet deals when the model says opportunity?
Because the grid is a person's view of the records. Every change made there still goes through the service that owns the opportunity, so the naming is presentation and nothing else.