Deal
Deal is how a conversation touches the deal record: it can create one, update its fields, read values out of it into flow variables, or attach another customer to it as a contact. It is a silent node — nothing is sent to the customer.
A deal is the business object the rest of the platform hangs work off: steps, fields, assets, simulations. See Deals API for the record itself.
One thing to understand before anything else: a customer and a deal are related many to many, through deal contacts. A deal is not a field on the customer and the customer is not a field on the deal. That is why the node has an explicit mode for adding a contact, and why reading "the customer's deal" goes through the contacts.
The four modes
The first thing you pick is the mode. Everything else on the panel depends on it.
| Mode | What it does |
|---|---|
| Create | Creates a deal, optionally sets its initial step, optionally links the conversation's customer as its primary contact, and can leave the new deal's ID in a variable |
| Update | Resolves one deal by ID and applies a list of update rules to it |
| Read | Finds one deal and copies values out of it into flow variables. Writes nothing |
| Add contact | Links a third customer — a guarantor, a co-signer — to an existing deal |
Create
The label
The deal's label comes either from a fixed value you type or from a flow variable. If you choose the variable and the variable does not exist at runtime, the node falls back to the fixed label instead of failing. With both empty, it exits through Error.
The label is not a template. Writing {{customer_name}} in it stores those characters
literally. The same applies to the description.
Linking the conversation's customer
Link customer is on by default. With it on you must pick a contact role from the
deal_role catalog, and the role is checked against that catalog before the deal is
created — so a bad role means no deal at all, rather than a deal left without its contact.
Two things to expect:
- With Link customer on and no role configured, the node exits through Error and creates nothing.
- With Link customer on but no customer identified in the conversation yet, the deal is created without a contact and the node leaves a warning notice saying so. It does not fail.
The contact created this way is always the deal's primary contact.
External ID
The external ID is your own identifier for the deal, from whatever system already owns it. It comes from a fixed value or a variable.
It is never unique. Writing an external ID that another deal of the tenant already carries leaves a warning notice and writes it anyway — "External id 'X' already belongs to deal Y; it was written anyway and now more than one deal carries it, so reading a deal by this external id will fail until one of them changes". That last part is the consequence that bites later: Read mode by external ID refuses to guess between two matches.
The rest
- Initial step — a key from the
deal_stepcatalog. Left empty, the deal is created without a step. - Fields — a list of
deal_fieldvalues, each from a fixed value or a variable. A field that fails to write leaves a warning notice and the node carries on with the others; a field whose value resolves to empty is skipped silently. - Test deal — off by default. It marks the deal as test data. Note that this is the toggle and nothing else: it is not inferred from the flow being a draft.
- Save deal ID to — the variable that receives the new deal's ID. This is the one output of Create mode, and it is what every later node needs in order to point at the deal.
Update
Update resolves the deal explicitly: from a variable holding a deal ID, or from an ID you type. It is never inferred from the customer. An unresolvable ID or a deal that does not exist exits through Error.
Then it applies a list of rules. Each rule names what to write and where the value comes from (a fixed value or a variable), exactly like Customer Update.
| Rule target | What it writes |
|---|---|
| Deal | One of the deal's own fields: label, description, status, riskRating, externalId. Anything else exits through Error with "'X' is not an updatable deal field" |
| Deal field | Upserts a value in the deal_field catalog |
| Step | Moves the deal to that step. No value needed |
Update writes no variables.
An external ID cannot be cleared here. An empty or blank value writes nothing and leaves the existing external ID untouched. There is no way to erase one from this node.
Money fields are checked, not guessed. A money or money_array value that does not
have the expected shape leaves a warning notice naming the problem and that one rule is
skipped — the rest of the node still applies. A money_array fed from a variable holding
bare money objects reports "the value holds bare money objects, so there is no key to file
them under" rather than inventing a key.
Read
Read finds exactly one deal and copies values out of it. It writes nothing to the deal.
Find by decides how:
| Find by | How the deal is found |
|---|---|
| Customer (default) | Through the conversation's customer's deal contacts, most recently created contact wins. No customer in the conversation is an Error |
| Deal ID | From a variable or a typed ID |
| External ID | From a variable or a typed value |
An external ID that matches more than one deal is an error, not a coin flip: "External id 'X' matches more than one deal; cannot decide which one to read". External IDs were never enforced unique, so picking one silently would make the flow read an unpredictable deal.
Outputs
Each output row names a value and the variable that receives it.
From the deal itself: id, externalId, label, description, status, riskRating,
currentStep, tags (joined into one string), createdAt, updatedAt. Any other key
exits through Error. From deal_field: any key in the catalog; a field that is not set
on the deal leaves a warning notice and the variable is left untouched.
All the outputs are written in a single update, so none of them is lost to a partial write.
A Read with no outputs configured finds the deal, leaves a warning notice — "The deal was found but the node has no outputs configured, so nothing was saved" — and continues.
Read does not change the type of a variable that already exists, only its value. If the variable was declared as something else, it keeps that declared type.
Add contact
This mode exists for the third party: a guarantor, a co-signer, someone who is on the deal but is not the person in the conversation.
The deal is resolved like in Update mode, from a variable or a typed ID. The customer comes from the variable you name in Customer ID variable, and that is the whole point of the mode — the customer is never taken from the conversation. That variable must hold a customer ID, not a document number; it is typically written a few nodes earlier by Create Borrower.
Three ways it exits through Error: no variable configured, a variable that does not exist, or a variable that is empty. None of them falls back to the conversation's customer.
The contact role is validated against the deal_role catalog before anything is
written, same as in Create.
Primary contact is off by default, and that is usually right: the primary contact is the debtor, a guarantor is not. Turning it on does more than flag the new contact — it demotes the deal's current primary contact for that same role.
Re-running the node does not duplicate anything. The same deal, customer and role combination is recognized and skipped. The same customer with a different role on the same deal is added.
Output Handles
| Handle | When |
|---|---|
| Continue | The mode completed. Warnings (a missing contact, a duplicate external ID, a skipped field) still exit here |
| Error | The deal or customer could not be resolved, a role is not in the catalog, a field is not updatable, or an unexpected failure |
Every Error exit leaves a notice on the conversation naming the cause, visible in the conversation's notices panel in Chat and aggregated in Flow Notices.
Connect the Error handle. A failure through an unconnected Error handle leaves a notice saying the node failed and had no Error handle, and the conversation falls back to the channel connector's default responder — or, without one, is left with no active flow.
Things to Know
Create always creates. There is no deduplication in Create mode: running it twice makes two deals. If the flow can re-enter that node, read first and branch.
The deal ID is the thing to keep. Create is the only mode that produces one, through Save deal ID to. Update, Add contact and Read-by-ID all need it. A flow that forgets to save it has no way back to the deal it just made.
Find by Customer picks by contact, not by deal. The winner is the most recently created deal contact, which is not always the most recently created deal.
Label and description are stored literally. No template rendering, unlike Create Asset.