Matching

Matching is the broker's workspace for turning a demand into a shortlist of candidate supply, aggregating producers when needed, and creating a deal. It is broker-only.

The guiding idea: "the engine is SQL plus the broker." Matching is deterministic and transparent — no machine learning, no black box. The platform proposes and explains; the broker decides.

Opening the workspace

From a demand (or the notification that a demand needs matching), the broker opens Matching for that demand. The workspace shows the demand at the top and a ranked list of candidate supply below.

How candidates are found

A supply entry is a candidate when it passes these hard rules:

• Same commodity as the demand.
• Active (published, not draft/withdrawn/expired).
• Window overlap — the supply's availability window overlaps the demand's need: it can be available on/before the needed-by date and not entirely before the demand's window start (or today, if no window start).
• Organic filter — if the demand requires organic, only organic-qualified supply is eligible.
• Certification schemes — required schemes are checked against the org's active certifications.

Two deliberate softenings:

• Missing required certs don't exclude — the candidate is still shown, with a warning, and ranked lower. The broker can override.
• Unverified organizations are included, with a warning — never silently dropped. Trust is a ranking factor, not a gate.

How candidates are ranked

Each candidate gets a score from five weighted factors, and — importantly — each factor comes with a plain-language "why" you can read in the score popover:

The total ranks the list; the per-factor breakdown ("Why matched") keeps it auditable — the broker can see exactly why one producer ranks above another. There is no hidden weighting and no learning loop.

A supplier in the Restricted band is ranked down and flagged, never removed — the same rule as an unverified organization, for the same reason. A supplier whose block has been confirmed by a person cannot be added to a deal at all, and the workspace says so rather than quietly omitting them. An operator with no score yet is ranked on its verification status alone.

Aggregation & reconciliation

One demand can be filled by several supply entries. The broker selects candidates (checkboxes); as they do, a running total reconciles the selected quantity against the demand:

• Matches the demand quantity → OK.
• Short by X → the broker can still proceed with a partial fill.
• Over by X → a non-blocking over-allocation warning; the broker trims an allocation to fit.

Reconciliation warns, never blocks — partial fills and slight overages are normal in agriculture, and the broker makes the call. Quantities in different units (kg vs tonnes) are converted automatically; genuinely incompatible units raise a "mixed units" warning to check the allocations.

Example (from the demo): a buyer needs 15 t organic chickpeas. Two producers have overlapping September windows — 9 t and 8 t. Selecting both gives 17 t (over by 2 — a warning, not a block). The broker trims one allocation to 6 t → 15 t → OK → Create deal.

Creating the deal

When the selection looks right, the broker clicks Create deal. In one atomic step OnlyTons:

• creates a deal at status inquiry with a DEAL-YYYY-NNNN reference;
• adds a line for each selected supply, with its allocated quantity;
• reserves each selected supply entry;
• moves the demand to in_deal;
• writes the opening events on the deal timeline.

From there, coordination happens in the deal room.

---

Next: Deals · Back to index