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

Preview matching bank transactions with open documents

POST
https://api.light.inc/v1/bank-accounts/{bankAccountId}/preview-clearing

Shows how clear-and-reconcile would pay open invoices receivable or invoices payable from unmatched bank transactions of this bank account: the allocation, fees, withholding, the balance left over, and whether the match is valid. It neither writes nor calls anything outside Light. Fails with 400 and BANK_RECONCILIATION_TRANSACTIONS_NOT_VALID when a bank transaction is already matched or excluded, and with BANK_RECONCILIATION_TOO_MANY_ITEMS when bankTransactionIds, accountingDocumentIds or allocation.items has more than 100 entries. Without an allocation it returns the one Light suggests; with one, it checks it.

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.

Response

  • accountingDocuments array of object

    The documents in the preview, with what is still open on each

    • id string · uuid

      ID of the accounting document

    • documentType string

      Document type: AR for an invoice receivable, AP for an invoice payable

      ⚠️ This enum is not exhaustive; new values may be added in the future.

      One of AP AR BP CC CN CT DE FX JE YC

    • currency string

      Currency of the document

    • outstandingBalance integer · int64

      Gross amount still open on the document, in minor units of its currency

    • withholding object

      Null when the document has no withholding tax

      • remainingToPay integer · int64

        Cash the document still expects: its gross still open, less the withholding that covers the rest. Payments are allocated against this amount, not outstandingBalance.

      • unavailableReason string

        Why this payment realizes none of the document's withholding, when it can't. The document then expects its whole open gross in cash, and remainingToPay says so.

        • CROSS_CURRENCY - The bank account's currency isn't the document's, and withholding is only realized by a payment in the document's currency

        ⚠️ This enum is not exhaustive; new values may be added in the future.

        One of CROSS_CURRENCY

  • 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

  • summary object

    Totals of the allocation, and whether clear-and-reconcile would accept it

    • currency string

      Currency of the bank account; every amount in the summary is in its minor units

    • availableAmount integer · int64

      Total of the bank transactions

    • allocatedAmount integer · int64

      Total the allocation takes from the bank transactions

    • fees integer · int64

      Total bank fees in the allocation

    • withheldAmount integer · int64

      Withholding the allocated payments realize, which settles the documents on top of the cash

    • remainingBalance integer · int64

      Amount of the bank transactions left unallocated. Must be zero for a valid match. For invoices receivable it is availableAmount plus fees less allocatedAmount, since fees were taken from what the customer paid; for invoices payable it is availableAmount less allocatedAmount and fees, since the bank charged them on top.

    • isValid boolean

      Whether clear-and-reconcile would accept this allocation. It is false when any of these holds: remainingBalance is not zero; the items of one document add up, in amountInInvoiceCurrency, to more than the document still takes, which is its withholding.remainingToPay when it has withholding and its outstandingBalance otherwise; a document that still takes a payment has no allocation item; an item paying a bill has an amountInInvoiceCurrency or amountInBankCurrency that is zero or negative, a negative feesInBankCurrency, or two amounts that differ although the bill and the bank account have the same currency; a document's withholding.unavailableReason is set. The checks on a single item's amounts run for bills only; the preview doesn't check them on an invoice item.