Deals

A deal is the coordinated transaction the broker builds from a demand and its matched supply. The deal room is where the broker drives it forward and where the parties follow along. Everything about a deal is designed around one rule: the broker coordinates; the parties see only what they should.

Anatomy of a deal

• Reference — DEAL-YYYY-NNNN, stamped when the deal is created.
• Status — where it is in the pipeline (below).
• Lines — one per supply allocation. An aggregated deal has several lines, possibly from different suppliers. Each line has an allocated quantity and (optionally) a line price.
• Timeline — the ordered history of events (status changes, messages, notes, price set, files), and the channel through which the portal relays messages between the parties (see visibility).
• Value & fee — once a price is agreed, the deal value and the broker's fee are computed (see Value & fees).
• Logistics & provenance — delivery details, and the provenance chain assembled from the lines.

The pipeline

The broker moves a deal through these stages (shown as Kanban columns on the Deals board):

inquiry ─▶ negotiating ─▶ agreed ─▶ in_fulfillment ─▶ delivered ─▶ closed
   └──────────────┴──────────┴───────────┴─────────────┴──▶ cancelled

• inquiry — just created from matching.
• negotiating — terms being worked out.
• agreed — price and quantity locked in. Guarded (see below).
• in_fulfillment — being produced/shipped.
• delivered — goods delivered.
• closed — done.
• cancelled — called off from any non-closed stage (a reason is required).

Two movement rules:

• You can step one stage backward (with a required reason, which is logged).
• cancelled is reachable from any non-closed stage, with a required reason.

The "agreed" guard

You cannot move a deal to agreed until it has both an agreed price and a total quantity. If you try (including by dragging the card on the Kanban), the move is blocked with "Set the agreed price…" and the card snaps back. This guarantees every agreed deal has the numbers needed to compute value and fees.

A deal can also be made to require its contracts: tick Contract required before this deal is agreed in the Contract group panel and the deal cannot reach agreed until every party has signed. It is off by default on every deal — whether a signature should be a precondition everywhere is a business decision that has not been taken — and it can only be set before the deal is agreed.

Stepping back, once a contract is in force

A deal cannot be moved back out of agreed while any of its contracts is in force. The pipeline is not allowed to say "we are still negotiating" while a signed agreement says the parties are committed.

The way out is to deal with the agreement rather than the card: suspend it, terminate it, or cancel the deal. Cancelling a deal ends its paperwork in the same step — an agreement that bound is terminated, one nobody had signed yet is withdrawn — so nobody is left holding a live contract for a deal that no longer exists.

What happens automatically (cascades)

Advancing a deal cascades to the supply and demand behind it — automatically, in one atomic step, so states never drift:

Cancelling also ends the deal's contracts in the same step, and reaching agreed on a deal whose contracts are all signed is something the contracts themselves can trigger.

* Only entries whose state legally allows it are released — e.g. a supply you separately withdrew stays withdrawn. The same rule applies to land.

The land column only applies to a deal that came from a crop proposal against a parcel — an ordinary goods deal has no land and nothing happens. Note the two blanks: land is not released at delivered or closed, because a parcel is not used up by a delivery. The crop comes off and the ground is there again next season, so putting an allocated parcel back on the market is a decision you or OnlyTons make, not a side effect of shipping.

Every transition writes a status-change event on the timeline and records activity for the dashboard. Reaching agreed records the deal's realized value; cancelling an already-agreed deal is flagged as leakage.

Timeline — who sees what

The deal timeline carries three kinds of events:

• All parties — status changes, price set, delivered. Facts about the deal that everyone on it is entitled to.
• Direct — addressed to one organization. Every message is one of these: you write to the portal, and the portal writes to the other side.
• Internal — broker only. OnlyTons's private working notes.

Internal events are filtered out before they reach a non-broker — a buyer loading the timeline never receives them at all (it's enforced in the data, not just hidden in the UI). This is a hard rule: keeping the broker's working notes private is central to the product.

Messages do not go to the other party. They go to OnlyTons, which reads them and passes them on. See Messaging and the relay for what that means in practice, why it works that way, and what stays fast.

Attachments

Parties can attach files to a deal (contracts, specs, photos). Attachments are stored privately and served only through short-lived signed links; every download re-checks that the requester is a party to the deal and allowed to see that file. Non-broker parties never receive internal attachments.

An attachment you upload goes to OnlyTons first, like a message — a filename such as Verdi-Farm-pricelist.pdf names you just as plainly as a signature would. When it is passed on, it carries a neutral display name.

Value & fees

When the broker sets the agreed price, OnlyTons computes:

• Deal value = total quantity × agreed unit price (exact decimal arithmetic, explicit currency).
• Fee — per the deal's fee model:
  • Take rate — a percentage of the deal value (default reporting rate 4%).
  • Flat or planning fee — a manually entered amount.
  • None — no fee.

Fees are measured, not charged in the MVP — they instrument the value the broker coordinates, which the dashboard reports. Value and fee are recomputed together whenever price or quantity changes.

The Deals board

• Broker sees a Kanban board — every deal as a card in its status column, draggable between columns (guards and required-reason prompts apply to drags too).
• Organization users see a My deals list — only the deals their organization is a party to, with the status and their own lines.

Who you see in a deal room

Parties are shown by per-deal alias — "Buyer", "Supplier A", "Supplier B" — alongside their operator handle and area. A supplier does not see who its co-suppliers are, and no party sees another's company name. The coordinator appears as OnlyTons — portal.

The deal title you see is derived from the goods (commodity · quantity · deadline); the broker keeps a separate internal title.

Logistics shows your own half of the journey: incoterms, transport mode, the area you collect from or deliver to, a delivery window, and a OnlyTons-issued transport reference (CR-2026-0042-S) to quote when you call. OnlyTons is the counterparty of record on both legs, so the paperwork names the portal rather than the operator at the other end. You do not see the other party's area — that, together with a quantity and a window, would be enough to work out who they are. See Operator privacy.

---

Next: Traceability & provenance · Back to index