# Closing a deal, end to end

Closing is a stage move like any other, so `move` applies the same stage rules and refuses a close it cannot satisfy. Won hands the person to onboarding and support; lost stops the chasing. Both settle the value, deal with the deal's open follow-ups, and leave a record of who decided and when — which is the part that gets asked about months later.

- **Status:** Available
- **Audience:** both
- **In the app:** #/sales, #/relationships
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/workflows/close-deal/

## The close is a move, not a button of its own

An opportunity in `sales.py` has a stage, a value and a review flag. Won and lost are positions on that stage list, reached through the same `move` every other progression uses, under the same stage rules. That is deliberate: if closing had its own path it would be the one path where a required field could be skipped, and the pipeline would fill with deals that were won on paper and had no value on them.

The value is held in **minor units** — `money(value_minor, currency)` — so a deal is stored as a whole number of the smallest unit of its currency and never as a float that drifts. A close is the moment that number stops being an estimate, so it is worth setting the real figure with `set_value` before the move rather than after it.

> **Careful** If the deal is under review — `raise_for_review` was called on it, usually because a commercial term needed a person — clear the review first with `clear_review`. Closing a deal that still carries an unanswered commercial question buries the question.

## The thirteen stages of a close

1. TRIGGER — a person decides the deal is done, or a conversation makes it plain: an order, a signed quotation, or a customer saying they have gone elsewhere.
2. USER / EXTERNAL EVENT — the decision arrives on the Sales screen, from the Assistant, or as a reply on a thread that a person then acts on. Connect does not decide on its own that a deal is won.
3. AUTH / WORKSPACE RESOLUTION — the opportunity belongs to exactly one workspace; the kernel scopes the query and row-level security backs it, so an Owner session and a customer session reach their own deals through the same code.
4. INGEST / REQUEST — `move` receives the opportunity, the target stage and the person making the change. A missing target is refused rather than guessed at.
5. CANONICAL RECORD — the opportunity's stage changes. The value, currency and any review flag travel with it; nothing is copied into a second 'closed deals' table that could disagree with the first.
6. CLASSIFICATION / RESEARCH / REASONING — the stage rules run. They are the reason a close can be refused: a rule that requires a value, or an order of stages, is checked here and reported rather than silently bypassed.
7. KNOWLEDGE + MEMORY + RULES — `safe_sales` still applies to anything said to the customer about the close. A price or a warranty term Knowledge does not support is refused and escalated, whether the deal is opening or closing.
8. AUTONOMY / APPROVAL — the move itself is a person's decision. Any message that goes out about it — a thank-you, a hand-over note — obeys the channel's autonomy mode like any other reply.
9. ACTION / PROVIDER — none for the move. A provider is only involved if a message accompanies it, and that leaves through the ordinary send boundary.
10. RESULT — the deal shows its new stage on the pipeline immediately. A refusal shows the rule that refused it, not a generic failure.
11. RELATIONSHIP / TIMELINE / MEMORY — the person's timeline gains the close; on a win, `journey` moves the lifecycle stage and `onboarding_action` becomes the next thing that matters; on a loss, the reason is worth writing as memory so the next conversation starts from it.
12. AUDIT / USAGE / NEEDS YOU — who closed it, when, from which stage, and under which rule is recorded. Anything that could not be completed — an unanswered commercial question, a follow-up that needs a decision — is left where a person will see it.
13. NEXT — a won deal becomes onboarding and then support; a lost one leaves a relationship that is still real and a set of follow-ups that should now stop.

## Stage by stage

| Stage | What you see | What changes | What can fail |
|---|---|---|---|
| Decision | You pick won or lost | Nothing yet | The deal is under review and the question behind the review is still open |
| Rules | A refusal, or nothing | Nothing on a refusal | A stage rule is unsatisfied — most often a missing value |
| Move | The card sits in its new column | Stage, and the value if you set one | Two people closing the same deal at once; the last write is the one that stands |
| Lifecycle | The person's stage changes on a win | `journey` position | A win with no company linked leaves onboarding attached to a person and not an organisation |
| Follow-ups | Open chases on the deal | Completed, cancelled or stopped by you | Nothing stops them for you — a lost deal that keeps ringing is a follow-up nobody closed |
| Record | The timeline entry | An audit row naming the person | Nothing: the record is written with the move, not afterwards |

## Won and lost are not mirror images

**Won** — The relationship gets busier, not quieter. `journey` moves the lifecycle stage, `onboarding_action` picks the person up, and support cases become the likely next record. Follow-ups about closing should be completed; follow-ups about delivery usually want creating.
**Lost** — The relationship stays. The person is still a person, the company is still a company, and the timeline still holds every exchange. What must stop is the chasing: `stop_for_person` or `stop_for_thread` is the honest end, and leaving the rows open is how a lost customer gets rung a fortnight later.
**Lost to a competitor** — Worth recording as memory rather than only as a stage, because the useful part is the reason. A stage says the outcome; memory says why, and the next conversation can start there.
**Reopened** — There is no special reopen. Move the stage back, and the timeline shows both moves in order — which is more honest than a deal that quietly forgets it was ever lost.

## What goes wrong here

- **The value is wrong by a factor of a hundred.** Values are minor units. A figure entered as though it were major units is out by the currency's exponent, and the pipeline total is the first place it shows.
- **Follow-ups outlive the deal.** Nothing cascades from a stage move to the follow-up rows on purpose — an automatic cancel would take out delivery chases as well as sales chases. Closing them is a step, not a side effect.
- **The close is refused and the refusal is read as a fault.** A stage rule that will not let a deal reach won without a value is doing its job; see [The deal would not move stage](/docs/troubleshooting/stage-move-refused/).
- **The deal disappears from the board.** Closed stages are usually filtered out of the default view rather than deleted; [A deal is not on the board](/docs/troubleshooting/deal-missing-from-pipeline/) walks the four reasons in order.

## Questions

### Can Connect close a deal on its own?

No. Connect can raise a deal for review, draft the message that surrounds a close and schedule the chasing, but the stage move to won or lost is a person's decision. That boundary is the same one that stops it inventing commercial terms.

### What happens to the demos attached to a deal?

A demo has its own lifecycle — requested, scheduled, completed or cancelled — and a close does not resolve it. A scheduled demo on a lost deal should be cancelled, and one on a won deal is often the onboarding session, so it is worth completing rather than deleting.

### Does the customer get told the deal was closed?

Only if somebody sends something. Marking a deal won or lost changes your records; it does not send a message. Any note that does go out is drafted and released under the channel's autonomy mode like any other reply.

## Related

- [Closing a deal: won and lost](https://connectbyjbrh.com/docs/sales/won-and-lost/)
- [Stage rules and refusals](https://connectbyjbrh.com/docs/sales/stage-rules/)
- [The pipeline board](https://connectbyjbrh.com/docs/sales/pipeline/)
- [Onboarding a new customer](https://connectbyjbrh.com/docs/support/onboarding/)
- [Completing a follow-up](https://connectbyjbrh.com/docs/follow-ups/completion/)
- [Lifecycle stages](https://connectbyjbrh.com/docs/relationships/lifecycle-stages/)

## What this page is based on

- `docs-source/sources/CHANNELS.md` §6 — sales, stage rules and `safe_sales`
- `docs-source/sources/CHANNELS.md` §5 — relationships, `journey` and cases
- `docs-source/sources/CHANNELS.md` §7 — follow-ups and support
- Connect capability registry (docs-source/facts.py)