Run Ledger Reconciliation

GET

finance

reconciliation

Run an on-demand ledger reconciliation

curl --request GET \
  --url https://billing.example.com/v1/finance/reconciliation \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://billing.example.com/v1/finance/reconciliation', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/v1/finance/reconciliation",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/finance/reconciliation"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/finance/reconciliation")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "started_at": "2023-11-07T05:31:56Z",
    "finished_at": "2023-11-07T05:31:56Z",
    "invoices_checked": 123,
    "paid_invoices_checked": 123,
    "total_discrepancies": 123,
    "discrepancies": [
      {
        "type": "<string>",
        "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "reference_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "expected_amount": 123,
        "found_amount": 123
      }
    ],
    "truncated": true,
    "tb_compared": true,
    "tb_skip_reason": "<string>"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

Reconciles the tenant’s invoices against its PostgreSQL ledger entries — and, when TigerBeetle is connected, diffs the Postgres ledger (authoritative) against TigerBeetle transfers — returning the computed drift report. The same check runs automatically once a day; discrepancies are logged as Ledger reconciliation found discrepancies.

Example Request

curl https://api.recurso.dev/v1/finance/reconciliation \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "tenant_id": "0b7a3f7e-4a2b-4c1d-9e8f-1a2b3c4d5e6f",
    "started_at": "2026-07-06T04:00:00Z",
    "finished_at": "2026-07-06T04:00:02Z",
    "invoices_checked": 58231,
    "paid_invoices_checked": 41207,
    "total_discrepancies": 2,
    "discrepancies": [
      {
        "type": "missing_payment_transaction",
        "invoice_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "expected_amount": 499900,
        "found_amount": 0
      },
      {
        "type": "tb_amount_mismatch",
        "transaction_id": "9b2f1c4d-3e5a-4b6c-8d7e-0f1a2b3c4d5e",
        "expected_amount": 129900,
        "found_amount": 128900
      }
    ],
    "truncated": false,
    "tb_compared": true,
    "tb_skip_reason": "",
    "tb_accounts_checked": 214,
    "tb_transfers_checked": 17352
  }
}

Report Fields

Field	Type	Description
`invoices_checked`	integer	Non-draft invoices covered by the run
`paid_invoices_checked`	integer	Paid invoices whose payment postings were verified
`total_discrepancies`	integer	Full discrepancy count, even when the listing is truncated
`discrepancies`	array	Up to 100 listed discrepancies
`truncated`	boolean	`true` when more discrepancies exist than are listed
`tb_compared`	boolean	Whether the TigerBeetle comparison pass ran
`tb_skip_reason`	string	Why the TigerBeetle pass was skipped (empty when it ran)
`tb_accounts_checked` / `tb_transfers_checked`	integer	Scope of the TigerBeetle pass

Discrepancy Types

`type`	Comparison	Meaning
`missing_invoice_transaction`	Billing ↔ Postgres	Non-draft invoice with no ledger posting
`invoice_amount_mismatch`	Billing ↔ Postgres	Invoice postings do not sum to the invoice total
`missing_payment_transaction`	Billing ↔ Postgres	Paid invoice with no payment posting
`payment_amount_mismatch`	Billing ↔ Postgres	Payment postings do not sum to `amount_paid`
`orphaned_transaction`	Billing ↔ Postgres	Posting references a non-existent invoice
`missing_in_tigerbeetle`	Postgres ↔ TigerBeetle	Postgres transaction with no matching transfer
`missing_in_postgres`	Postgres ↔ TigerBeetle	TigerBeetle transfer with no matching transaction
`tb_amount_mismatch`	Postgres ↔ TigerBeetle	Same transaction ID, different amounts

Each discrepancy carries the relevant identifier (invoice_id, transaction_id, or reference_id) plus expected_amount and found_amount in minor units.

`tb_skip_reason`

The TigerBeetle pass never fails the report — when it cannot run, tb_compared is false and tb_skip_reason says why:

Not connected — TigerBeetle is not configured for this deployment (normal: PostgreSQL is the authoritative ledger)
Above the memory guard — the tenant has more than 100,000 ledger transactions or transfers; the in-memory diff is skipped rather than risking an OOM
Read failure — enumerating transfers or loading transaction summaries errored (the message includes the underlying error)

This GET is computed on demand and never persisted — it only reads. Correcting drift (e.g. with a reversing entry) is a deliberate human action. If you want an audit trail of when reconciliation ran and what it found, use Reconciliation Run History to run and record a summary. See the ledger guide and the incident runbook’s SEV1 procedure for how to act on a non-zero report.

Authorizations

Authorization

string

header

required

Tenant API key obtained from POST /auth/register or POST /v1/developer/keys.

Response

Reconciliation report.

data

object

Show child attributes

Run an on-demand ledger reconciliation

curl --request GET \
  --url https://billing.example.com/v1/finance/reconciliation \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://billing.example.com/v1/finance/reconciliation', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/v1/finance/reconciliation",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/finance/reconciliation"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/finance/reconciliation")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "started_at": "2023-11-07T05:31:56Z",
    "finished_at": "2023-11-07T05:31:56Z",
    "invoices_checked": 123,
    "paid_invoices_checked": 123,
    "total_discrepancies": 123,
    "discrepancies": [
      {
        "type": "<string>",
        "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "reference_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "expected_amount": 123,
        "found_amount": 123
      }
    ],
    "truncated": true,
    "tb_compared": true,
    "tb_skip_reason": "<string>"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Run Ledger Reconciliation

Example Request

Response

Report Fields

Discrepancy Types

`tb_skip_reason`

Authorizations

Response

​Example Request

​Response

​Report Fields

​Discrepancy Types

​tb_skip_reason

Authorizations

Response

Example Request

Response

Report Fields

Discrepancy Types

`tb_skip_reason`