Reconciliations

Reconciliations are used to match and verify financial transactions across different accounts or statements. They help ensure the accuracy of accounting records by confirming that transactions are properly recorded and balanced.

Endpoints

Query Parameters

The GET /reconciliations endpoint supports the following query parameters:

Attributes

Relationships

All relationships are opt-in and must be requested via the with query parameter.

Reconciliation Entry

Example Request

GET /api/v2/reconciliations?client_account_id=7&with=entries,entries.journal_entry_line,created_by

Example Response

{
    "data": [
        {
            "id": 1,
            "created_at": "2023-05-10T12:00:00Z",
            "created_by_id": 1,
            "client_account_id": 7,
            "sequence_number": 1,
            "reconciliation_date": "2023-05-10",
            "is_draft": false,
            "is_deleted": false,
            "deleted_at": null,
            "deleted_by_id": null,
            "entries": [
                {
                    "id": 1,
                    "journal_entry_id": 1,
                    "journal_entry_line_id": 1,
                    "debit": "100.00",
                    "debit_fc": "100.00",
                    "credit": "0.00",
                    "credit_fc": "0.00",
                    "journal_entry_line": {
                        "id": 1,
                        "posting_date": "2023-05-10",
                        "description": "Bank transaction",
                        "account_code": "1920",
                        "account_id": 1,
                        "debit": "100.00",
                        "credit": "0.00"
                    }
                }
            ],
            "created_by": {
                "id": 1,
                "first_name": "John",
                "last_name": "Doe"
            }
        }
    ],
    "meta": {
        "page": 0,
        "pages": 1,
        "per_page": 100,
        "records": 1
    }
}

Create Reconciliation

POST /api/v2/reconciliations

Creates a committed reconciliation matching two or more journal entry lines. The entries relation is included in the response by default.

Request Body

Entry line fields

This endpoint always creates a committed reconciliation (is_draft: false) — is_draft cannot be set through the request body. Draft (proposal) reconciliations are produced only by Snapbooks’ internal automatic-matching pipeline and approved via Update Reconciliation.

Across all entries, local-currency (debit/credit) amounts must always balance to zero. If every entry shares one foreign currency and only the local-currency side is unbalanced, an offsetting FX gain/loss (agio) entry is posted automatically. If entries span more than one currency, foreign-currency amounts aren’t summed (mixing currencies is meaningless) — any local-currency residual must instead be balanced by an agio/disagio entry line supplied in the request; there’s no auto-posting for the cross-currency case.

For an entry that reconciles part of a journal entry line carrying a foreign-currency amount, debit_fc/credit_fc and debit/credit must preserve the line’s own implied rate (line.debit_or_credit / line.debit_fc_or_credit_fc) — not the line’s stored exchange_rate, which upstream postings sometimes fit to an external constraint. A 1-minor-unit rounding tolerance on the local-currency side absorbs frontend/backend rounding noise; anything past that is rejected rather than silently restated. Post a settlement-rate difference as a separate agio line instead of folding it into the entry.

Example Request

{
  "client_account_id": 7,
  "date": "2026-04-10",
  "entry_lines": [
    { "journal_entry_line_id": 101, "debit": "0", "credit": "500.00" },
    { "journal_entry_line_id": 205, "debit": "500.00", "credit": "0" }
  ]
}

Response

Returns the created reconciliation with status 201 Created, including its entries.

{
  "id": 42,
  "created_at": "2026-04-10T09:15:00Z",
  "created_by_id": 7,
  "client_account_id": 7,
  "sequence_number": 12,
  "reconciliation_date": "2026-04-10",
  "is_draft": false,
  "entries": [
    {
      "id": 88,
      "journal_entry_id": 501,
      "journal_entry_line_id": 101,
      "debit": "0.00",
      "debit_fc": "0.00",
      "credit": "500.00",
      "credit_fc": "500.00"
    },
    {
      "id": 89,
      "journal_entry_id": 502,
      "journal_entry_line_id": 205,
      "debit": "500.00",
      "debit_fc": "500.00",
      "credit": "0.00",
      "credit_fc": "0.00"
    }
  ]
}

Error Responses

Update Reconciliation

PATCH /api/v2/reconciliations/{id}

Approves a draft reconciliation, committing it. is_draft is the only mutable field, and only in the draft → committed direction — reopening a committed reconciliation back to draft is rejected. To undo a committed reconciliation, use Delete Reconciliation instead.

Path Parameters

Request Body

Behavior

• If the reconciliation is already committed, the request is a no-op and returns the current state with 200 OK.
• Otherwise, each cited journal entry line is re-checked to confirm it still has enough open amount to absorb the draft’s applied amount. If a cited line (or its journal entry) was cancelled or reconciled elsewhere since the draft was proposed, the stale draft is deleted and the request fails with 409 Conflict.
• On success, the reconciliation is assigned a sequence_number, is_draft becomes false, and the cited journal entry lines and linked documents update their reconciled status — the same effect as Create Reconciliation.

Example Request

{ "is_draft": false }

Response

Returns the updated reconciliation with status 200 OK, including its entries.

Error Responses

Delete Reconciliation

DELETE /api/v2/reconciliations/{id}

Undoes a reconciliation. The journal entry lines and their journal entries remain in place — the reconciled amount is released.

• Draft reconciliations are proposals, not reconciled state — deleting one hard-deletes it.
• Committed reconciliations are soft-deleted instead of removed: deleted_at/deleted_by_id are set and is_deleted becomes true, so the delete-and-redo is retained for audit and downstream signal. Soft-deleted reconciliations are hidden from GET /reconciliations unless is_deleted=true is requested.

Response

Returns 204 No Content with an empty body on success. Deleting an already soft-deleted reconciliation is idempotent — it returns 204 again rather than a 409 (unlike Update Reconciliation, which does 409 on an already-deleted draft).

Error Responses

Notes

• The client_account_id must be one of the eligible client accounts for the authenticated user.
• Reconciliations can only be created, updated, or deleted if they belong to one of the user’s eligible client accounts.
• The entries, entries.journal_entry_line, and created_by relations are opt-in on GET — request them through with. POST and PATCH responses include entries by default.
• All amounts are returned as string representations of decimal numbers.
• All dates are returned in ISO 8601 format.
• The _fc suffix on amount fields represents “foreign currency” amounts.
• DELETE on a committed reconciliation is a soft delete (is_deleted: true, deleted_at/deleted_by_id set), not a removal — the row stays queryable via GET /reconciliations?is_deleted=true. DELETE on a draft is a hard delete, since a draft is just an unapproved proposal.