Split and aggregate matches

Real-world reconciliation often involves transactions that don’t match 1:1. A single payment may cover multiple invoices, or several deposits may consolidate into one bank entry. Matcher handles these complex scenarios through split and aggregate matching.

Overview

The context type controls matching cardinality. Matcher supports three context types:

Context type	Description	Example
1:1 — one to one	One source to one target	Single invoice payment
1:N — one to many	One left-side transaction to many right-side transactions, for a split or an aggregate	Bulk payment covering invoices; deposits consolidated at a bank
N:M — many to many	Any combination of sources and targets	Complex netting

There is no separate N:1 context type. The single transaction is always on the left side. For an aggregate, put the source that carries the consolidated entry on the left side.

How it works

Two mechanisms control split and aggregate behavior:

Context type: determines the matching cardinality (1:1, 1:N, or N:M).
Rule allocation flags: control how Matcher distributes amounts within a match group.

There is no separate “split” or “aggregate” setting on the context. The context type defines the allowed patterns, and the rule config controls allocation behavior.

Context type mapping

Context type	Allowed patterns
`1:1`	One source to one target only
`1:N`	One left-side transaction to many right-side transactions
`N:M`	Any combination of sources and targets

Rule allocation settings

All rule types accept allocation flags in their config. Matcher applies them in 1:N contexts:

Field	Type	Description
`allowPartial`	Boolean	Allow partial allocation of transaction amounts
`allocationToleranceMode`	String	How tolerance is measured: `ABS` (absolute) or `PERCENT`
`allocationToleranceValue`	Decimal	Tolerance threshold for allocation residuals
`allocationUseBaseAmount`	Boolean	Allocate base (converted) amounts. It also turns on `matchBaseAmount` and `matchBaseCurrency`
`feeAware`	Boolean	Fee-aware 1:N allocation: consume each candidate’s gross share (net + fee) instead of net only. Useful for marketplace splits where the payout is net of fees
`nmDeductionBand`	Decimal	TOLERANCE rules in `N:M` contexts only. Short-pay band for the N:M solver, as a decimal fraction of the short invoice face (`0.05` = 5%). Lets a payment subset under-pay an invoice subset within the band. Zero or absent disables it

Example: split rule with allocation

In a 1:N context, each right-side transaction must pass the rule’s checks against the left-side transaction. A rule that compares amounts matches only legs equal to the whole, so a split rule turns matchAmount off and lets allocation check the total. TOLERANCE rules always compare amounts.

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 2,
   "config": {
     "matchAmount": false,
     "matchReference": false,
     "allowPartial": true,
     "allocationToleranceMode": "ABS",
     "allocationToleranceValue": 10.0
   }
 }'

Creating a 1:N context

To enable split or aggregate matching, create a context with type 1:N:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Payment Reconciliation",
   "type": "1:N",
   "interval": "daily"
 }'

API Reference: Create context

1:N split matching

One left-side transaction matches many right-side transactions.

Common use cases

Bulk payment: Single wire covering multiple invoices
Payroll: One bank debit for multiple salary payments
Settlement: One gateway payout for multiple orders

Example: bulk invoice payment

Left side (Bank Statement):

ID	Amount	Reference
bank_001	$15,000.00	BULK-PAY-2024-001

Right side (Ledger Entries):

ID	Amount	Invoice
inv_001	$5,000.00	INV-2024-001
inv_002	$7,500.00	INV-2024-002
inv_003	$2,500.00	INV-2024-003

Result: 1:3 match with full allocation

Aggregate matching (many-to-one)

Many transactions match one consolidated transaction. This uses the 1:N context type with the consolidated source on the left side. There is no separate N:1 type.

Common use cases

Bank deposits: Multiple checks deposited as one credit
Card settlements: Daily batch of transactions as one deposit
Cash consolidation: Multiple register receipts to one deposit

Example: consolidated deposit

Right side (Point of Sale):

ID	Amount	Register
pos_001	$1,250.00	REG-01
pos_002	$980.00	REG-02
pos_003	$1,770.00	REG-03

Left side (Bank Statement):

ID	Amount	Reference
bank_002	$4,000.00	DEPOSIT-20240120

Result: 3:1 match with full allocation

N:M many-to-many matching

Multiple source transactions match multiple target transactions. This is the most complex pattern.

Common use cases

Intercompany netting: Multiple invoices netted against multiple payments
Trade settlements: Complex clearing with partial fills
Revenue recognition: Multiple deliveries against multiple advances

Example: intercompany netting

Sources (Company A Payables):

ID	Amount	Reference
pay_001	$10,000.00	IC-PAY-001
pay_002	$8,000.00	IC-PAY-002

Targets (Company A Receivables):

ID	Amount	Reference
rec_001	$12,000.00	IC-REC-001
rec_002	$6,000.00	IC-REC-002

Result: 2:2 match, $18,000 total matched To enable N:M matching, create a context with type N:M:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Intercompany Netting",
   "type": "N:M",
   "interval": "weekly"
 }'

Running and reviewing matches

After configuring the context and rules, trigger a matching run and review the resulting groups.

Run matching

cURL

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "DRY_RUN"
 }'

A DRY_RUN run reports its statistics but stores no match groups. To list match groups, run with COMMIT.

View match run history

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/runs" \
 -H "Authorization: Bearer $TOKEN"

View a run’s match groups

You must send the contextId query parameter. The response is a cursor-paginated list of match groups, each containing its matched transactions (across all cardinalities) and confidence scores.

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN"

Break (unmatch) a match group

To reverse an incorrect group, unmatch it. Matcher rejects a PROPOSED group and revokes a CONFIRMED group. In both cases, its transactions return to UNMATCHED. Revoking a CONFIRMED group also withdraws its open-item residuals, voids its fee variances, and withdraws the exceptions it raised, in the same transaction. You must send the contextId query parameter and a reason in the body.

cURL

curl -X DELETE "https://api.matcher.example.com/v1/matching/groups/{matchGroupId}?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "incorrect match - amounts do not match"
 }'

Matching algorithm

The algorithm depends on the context type.

1:N deterministic sequential allocation

For split and aggregate (1:N) scenarios, Matcher uses deterministic sequential allocation:

Sort: Matcher sorts transactions deterministically to ensure reproducible results across runs.
Collect: For each left-side transaction, Matcher collects the right-side transactions that pass the rule’s checks against it.
Allocate: Matcher allocates the collected transactions in sort order and stops when the remaining amount is within the allocation tolerance. It skips a transaction in another currency. It allocates only transactions with the settling sign of the context’s signConvention: the sign of the left-side transaction under SAME (the default), the opposite sign under OPPOSITE.
Track residuals: Matcher tracks any remaining unallocated amounts. If allowPartial is true, Matcher caps an overshooting leg to the remaining amount. An under-covered split still surfaces a diagnostic exception.

N:M set-matching solver

For N:M scenarios, Matcher does not allocate sequentially. It uses a bounded subset-selection solver. The solver buckets candidates by the rule’s match identity. It then searches for a subset of left transactions and a subset of right transactions that reconcile against each other. A group holds at most 4 transactions per side. Matcher skips a bucket that holds more than 40 transactions on either side. Only EXACT and TOLERANCE rules run in N:M contexts. Selection remains deterministic over the sorted input. Each proposed group must clear the fixed confidence gate (minimum score 60). No transaction lands in two proposed groups within a run. On TOLERANCE rules, the nmDeductionBand key lets the solver admit a payment subset that under-pays an invoice subset within the band.

Exception reasons

Transactions that Matcher cannot fully reconcile surface as typed exceptions:

SPLIT_INCOMPLETE: allocations exist but do not fully cover the target amount, regardless of allowPartial.
OVER_SETTLED: a transaction over-settled an obligation that an earlier run carried open. Matcher surfaces the over-settled remainder as a typed break.

You can filter the exceptions list by these reason values.

Best practices

Start with 1:N before N:M

Many-to-many matching is complex. Start with simpler patterns and enable N:M only when necessary.

Use allocation tolerance for rounding

Small rounding differences are common in split payments. Set allocationToleranceValue to a few cents to avoid false exceptions.

Enable partial allocation deliberately

Set allowPartial to true only when you expect partial matches. This prevents false matches from incomplete data.

Dry-run before committing

Always test split and aggregate matching in DRY_RUN mode first, and read the run statistics. A dry run stores no match groups.

Monitor residuals

Track residual amounts over time. Growing residuals may indicate systematic matching issues.

Overview

Guides

Console

MCP Server

Operations

Split and aggregate matches

Overview

How it works

Context type mapping

Rule allocation settings

Example: split rule with allocation

Creating a 1:N context

1:N split matching

Common use cases

Example: bulk invoice payment

Aggregate matching (many-to-one)

Common use cases

Example: consolidated deposit

N:M many-to-many matching

Common use cases

Example: intercompany netting

Running and reviewing matches

Run matching

View match run history

View a run’s match groups

Break (unmatch) a match group

Matching algorithm

1:N deterministic sequential allocation

N:M set-matching solver

Exception reasons

Best practices

Next steps

Match Rules

Security

​Overview

​How it works

​Context type mapping

​Rule allocation settings

​Example: split rule with allocation

​Creating a 1:N context

​1:N split matching

​Common use cases

​Example: bulk invoice payment

​Aggregate matching (many-to-one)

​Common use cases

​Example: consolidated deposit

​N:M many-to-many matching

​Common use cases

​Example: intercompany netting

​Running and reviewing matches

​Run matching

​View match run history

​View a run’s match groups

​Break (unmatch) a match group

​Matching algorithm

​1:N deterministic sequential allocation

​N:M set-matching solver

​Exception reasons

​Best practices

​Next steps

Match Rules

Security

Overview

How it works

Context type mapping

Rule allocation settings

Example: split rule with allocation

Creating a 1:N context

1:N split matching

Common use cases

Example: bulk invoice payment

Aggregate matching (many-to-one)

Common use cases

Example: consolidated deposit

N:M many-to-many matching

Common use cases

Example: intercompany netting

Running and reviewing matches

Run matching

View match run history

View a run’s match groups

Break (unmatch) a match group

Matching algorithm

1:N deterministic sequential allocation

N:M set-matching solver

Exception reasons

Best practices

Next steps