Config reference

Top level

version: 1
timezone: "UTC"

Field	Required	Description
`version`	yes	Config schema version. Currently `1`.
`timezone`	no	Default IANA timezone for date parsing when a source doesn’t set `tz`. Defaults to `UTC`.

`sources`

Each source maps one file family into Reconify’s normalized transaction shape.

sources:
  left_source:
    file_pattern: "path/to/left-files/*.csv"
    parser:
      type: csv
      date_col: "Date"
      date_layout: "2006-01-02"
      amount_col: "Amount"
      decimal: "."
      thousands: ","
      multiplier: 100
      currency_col: "Currency"
      name_col: "Details"
      ref_col: "Reference"
      group_col: "Reference"

Field	Required	Description
`file_pattern`	yes	Path or glob `reconcile` reads when no explicit `--left-file`/`--right-file` is given.

Parser fields

Field	Required	Description
`type`	no	`csv`, `json`, `xlsx`, or `auto`. `auto` (or omitted) infers from the extension: `.csv`, `.json`/`.ndjson`, `.xlsx`/`.xlsm`.
`sheet`	no	XLSX/XLSM sheet name. Defaults to the first sheet.
`date_col`	yes	Column that contains the transaction date.
`date_layout`	yes	Go time layout, such as `2006-01-02`.
`tz`	no	IANA timezone for parsing dates that lack an offset. Defaults to `UTC`.
`amount_col`	yes	Column that contains the amount.
`decimal`	no	Decimal separator, one character. Defaults to `.`.
`thousands`	no	Thousands separator, one character.
`multiplier`	yes	Converts the parsed amount to minor units. Must be greater than zero.
`currency_col`	no	Currency code column.
`name_col`	no	Description or merchant name column.
`ref_col`	no	Reference, transaction ID, or order ID column: the matching key.
`group_col`	no	Duplicate-detection key, independent of `ref_col`. Falls back to `ref_col` when omitted. Use it when several rows legitimately share a reference, such as an invoice paid in installments, but each row has its own unique matching identifier.
`skip_raw`	no	Skip raw row map allocation, for lower memory use on large sources.

Column lookup is case-insensitive. Missing optional columns (ref_col, name_col, currency_col) are silently ignored rather than rejected.

Parser types

Type	Files
`auto` or empty	Infer from `.csv`, `.json`, `.ndjson`, `.xlsx`, `.xlsm`.
`csv`	CSV files with a header row.
`json`	JSON arrays and NDJSON objects.
`xlsx`	Modern Excel workbooks (`.xlsx`, `.xlsm`).

Legacy .xls files are not supported.

Date layouts

Reconify uses Go reference-time layouts, not strftime or YYYY-MM-DD:

date_layout: "2006-01-02"  # 2026-06-16
date_layout: "02/01/2006"  # 16/06/2026

Amount examples

amount_col: "Amount"
decimal: "."
thousands: ","
multiplier: 100

1,234.56 becomes 123456 (1,234.56 in minor units).

amount_col: "amount"
multiplier: 1

123456 stays 123456 (already minor units, 1,234.56). Parenthetical negatives are supported: (1,234.56) becomes -123456.

`pairs`

Pairs define which sources to reconcile against each other and what tolerances apply.

pairs:
  left_source_vs_right_source:
    left: left_source
    right: right_source
    date_window: "1d"
    amount_tolerance_minor: 0
    name_mode: "tokens"
    name_match_threshold: 0.5
    result_mode: "all"

Field	Required	Description
`left`	yes	Source name for the left side.
`right`	yes, unless `rights` is set	Single counterpart source name. Mutually exclusive with `rights`.
`rights`	yes, unless `right` is set	Ordered list of counterpart source names for multi-counterpart runs. Mutually exclusive with `right`. Each entry must be non-empty and unique. See Sources and pairs.
`date_window`	no	Timing tolerance, such as `1d` or `2d`.
`amount_tolerance_minor`	no	Amount tolerance in minor units. Defaults to `0`.
`name_mode`	no	`none` (default) or `tokens`. `tokens` enables name-token similarity matching after reference matching.
`name_match_threshold`	no	Jaccard similarity threshold for `name_mode: tokens`, where `0 < x < 1`. Defaults to `0.5`. `1.0` is rejected: a strict comparison against a ceiling could never match.
`result_mode`	no	Which events the writer emits: `all` (default), `exceptions_only`, or `summary_only`. See `reference/output`.

Recommended defaults: use name_mode: none when both sources have reliable references. Use name_mode: tokens when references are sparse but names or descriptions are consistent. Start amount_tolerance_minor at 0, and widen it only once you’ve confirmed a known rounding difference between the source systems.

`passes`

By default, a pair runs reference matching, then optional name-token matching when name_mode: tokens is set. Declare passes for explicit control over the matching pipeline:

pairs:
  left_source_vs_right_source:
    left: left_source
    right: right_source
    date_window: "1d"
    amount_tolerance_minor: 0
    passes:
      - type: reference_one_to_one
      - type: name_tokens_one_to_one

Pass type	`group_by`	Description
`reference_one_to_one`	n/a	Matches one left row to one right row by reference. The default first tier.
`name_tokens_one_to_one`	n/a	Matches remaining unmatched rows by Jaccard token similarity on the name field. Equivalent to `name_mode: tokens`.
`one_to_many`	`reference` \| `name` \| `group_key` (default `reference`)	Sums right rows sharing a group key and compares the total to one left row. See Matching algorithm.
`many_to_many`	`reference` \| `name` \| `group_key` (default `reference`)	Sums both sides’ rows sharing a group key and compares the totals. See Matching algorithm.

Passes run in the order listed. Each pass sees only rows earlier passes left unmatched. Omitting passes preserves the default reference-then-tokens behavior. When passes is set, name_mode: tokens is rejected: add a name_tokens_one_to_one pass explicitly instead. rights and passes are orthogonal and combine freely: rights selects which counterpart sources to reconcile against, in order; passes defines the matching strategy used within each counterpart.

`index`

Reconify builds an index for the right source before matching the left source. The index backend controls how that index is stored.

index:
  backend: auto
  spill_dir: "/tmp/reconify"
  auto_max_right_file_mb: 2048
  partition_count: 32
  max_memory_mb: 8192
  max_temp_disk_mb: 16384

Field	Required	Description
`backend`	no	`memory`, `disk`, `auto` (default), or `partitioned`.
`spill_dir`	no	Directory for `disk`/`auto`/`partitioned` temporary files. Defaults to the system temp directory.
`auto_max_right_file_mb`	no	File-size threshold above which `auto` selects `disk` instead of `memory`. Defaults to `2048`.
`partition_count`	no	Partition count for `partitioned`. `0` selects adaptively; explicit values must be `>= 2`.
`max_memory_mb`	no	Resource safeguard for `auto`. `0` leaves the budget uncapped.
`max_temp_disk_mb`	no	Resource safeguard for `auto`/`partitioned`. `0` leaves the budget uncapped.

Backend	Use when
`memory`	The right-side index fits comfortably in RAM. Fastest.
`disk`	Lower RAM usage, SQLite-backed spill, slower point lookups.
`auto`	No budgets: threshold-based selection against `auto_max_right_file_mb`. With `max_memory_mb`/`max_temp_disk_mb` set: resource-aware fallback through memory, then disk, then partitioned.
`partitioned`	Bounded memory for a large single-counterpart CSV run, including grouped passes, at the cost of extra sequential disk passes.

With either budget configured, auto records why each candidate backend was accepted or rejected in structured output. These are resource safeguards, not throughput guarantees: an unmet estimate fails the run explicitly rather than silently degrading. See Handle large files for the full tuning guide.

Full example

version: 1
timezone: "UTC"

index:
  backend: auto
  auto_max_right_file_mb: 2048

sources:
  left_source:
    file_pattern: "path/to/left-files/*.csv"
    parser:
      type: csv
      date_col: "Date"
      date_layout: "2006-01-02"
      amount_col: "Amount"
      decimal: "."
      thousands: ","
      multiplier: 100
      currency_col: "Currency"
      name_col: "Memo"
      ref_col: "SettlementBatchID"

  right_source:
    file_pattern: "path/to/right-files/*.csv"
    parser:
      type: csv
      date_col: "settlement_date"
      date_layout: "2006-01-02"
      amount_col: "net_amount"
      multiplier: 100
      currency_col: "currency"
      name_col: "description"
      ref_col: "batch_id"

  another_source:
    file_pattern: "path/to/another-files/*.csv"
    parser:
      type: csv
      date_col: "settlement_date"
      date_layout: "2006-01-02"
      amount_col: "net_amount"
      multiplier: 100
      currency_col: "currency"
      name_col: "description"
      ref_col: "batch_id"

pairs:
  left_source_vs_counterparts:
    left: left_source
    rights: [right_source, another_source]
    date_window: "2d"
    amount_tolerance_minor: 0
    passes:
      - type: many_to_many
        group_by: reference

This config reconciles left_source against two counterparts in order, using many_to_many to group and sum rows sharing a reference on both sides, with auto choosing the index backend per counterpart file size.

Start here

Concepts

Guides

Reference

Help

Top level

`sources`

Parser fields

Parser types

Date layouts

Amount examples

`pairs`

`passes`

`index`

Full example

​Top level

​sources

​Parser fields

​Parser types

​Date layouts

​Amount examples

​pairs

​passes

​index

​Full example

Top level

`sources`

Parser fields

Parser types

Date layouts

Amount examples

`pairs`

`passes`

`index`

Full example