New Light partners with Greenstep to bring agentic finance to the NordicsLight partners with Greenstep Read the announcement

Match bank transactions with open documents

POST
https://api.light.inc/v1/bank-accounts/{bankAccountId}/clear-and-reconcile

Registers a bank payment for each allocation item against its open invoice receivable or invoice payable, then matches the bank transactions with the bank payments' lines on this bank account's ledger account, all in one transaction. Fails with 400 and error type BANK_RECONCILIATION_INVALID_CLEARING when the preview of the same request is not valid; the description of summary.isValid on preview-clearing lists what makes it so, each in terms of fields the preview returns. More than 100 bankTransactionIds, accountingDocumentIds or allocation.items fail with BANK_RECONCILIATION_TOO_MANY_ITEMS. When a payment date falls in a closed period it fails with ACCOUNTING_PERIOD_CLOSED; retry with a clearingDate in an open period. A bank transaction that is already matched or excluded fails with BANK_RECONCILIATION_TRANSACTIONS_NOT_VALID before any payment is registered, so retrying a request that already succeeded changes nothing. An invoice or bill paired with one in another entity pays both sides and needs intercompanyCounterpartLedgerAccountId; without it the request fails with INTERCOMPANY_COUNTERPART_ACCOUNT_MISSING and writes nothing.

Authorization

Send one of these on every request. See Authentication for how to get credentials.

  • API key

    Basic authentication header of the form Basic <api_key>, where <api_key> is your api key.

  • Bearer token

Path parameters

  • bankAccountId string · uuidrequired

Request body

application/json;charset=UTF-8

  • bankTransactionIds array of string · uuidrequired

    IDs of unmatched bank transactions of this bank account

  • accountingDocumentIds array of string · uuidrequired

    IDs of open invoices receivable (AR) or open invoices payable (AP), at most 100. AR and AP can't be mixed in one match.

  • allocation object

    How the bank transactions pay the documents, at most 100 items. Leave it out to use the allocation Light suggests, the one the preview returns for the same bank transactions and documents.

    • items array of objectrequired

      One item per payment to register against a document

      • accountingDocumentId string · uuidrequired

        ID of the invoice receivable (AR) or invoice payable (AP) the payment clears

      • amountInInvoiceCurrency integer · int64required

        Amount the payment clears, in minor units of the invoice's currency

      • amountInBankCurrency integer · int64required

        Amount taken from the bank transactions, in minor units of the bank account's currency. Equals amountInInvoiceCurrency when both currencies are the same.

      • paymentDate string · daterequired

        Date the payment is registered on

      • feesInBankCurrency integer · int64required

        Bank fees booked with this payment, in minor units of the bank account's currency; 0 when there are none

  • clearingDate string · date

    Date to register every payment on, instead of the bank transaction date. When given, it replaces the paymentDate of every allocation item. Use it to clear into an open period when the bank transaction date falls in a closed one.

  • intercompanyCounterpartLedgerAccountId string · uuid

    Required when the document is an invoice or bill paired with one in another entity of the company, and not allowed otherwise. Clearing a paired document pays both sides. For a bill, this is the ledger account of the bank account that receives the payment on the invoice side; for an invoice, the one that pays the bill. A paired document has to be cleared on its own.

Response

  • id string · uuid

    Unique identifier for the matching group

  • bankTransactionIds array of string · uuid

    IDs of the bank transactions in the match, now MATCHED

  • ledgerTransactionLineIds array of string · uuid

    IDs of the ledger transaction lines in the match. When documents were cleared, these are the lines of the bank payments the clearing created; list them with matchingGroupId:eq:<id> on GET /v1/bank-accounts/{bankAccountId}/ledger-transaction-lines to find each bank payment's accountingDocumentId.