Preview matching bank transactions with open documents
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
-
bankAccountIdstring · uuidrequired
Request body
application/json;charset=UTF-8
-
bankTransactionIdsarray of string · uuidrequiredIDs of unmatched bank transactions of this bank account
-
accountingDocumentIdsarray of string · uuidrequiredIDs of open invoices receivable (AR) or open invoices payable (AP), at most 100. AR and AP can't be mixed in one match.
-
allocationobjectHow 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.
-
itemsarray of objectrequiredOne item per payment to register against a document
-
accountingDocumentIdstring · uuidrequiredID of the invoice receivable (AR) or invoice payable (AP) the payment clears
-
amountInInvoiceCurrencyinteger · int64requiredAmount the payment clears, in minor units of the invoice's currency
-
amountInBankCurrencyinteger · int64requiredAmount taken from the bank transactions, in minor units of the bank account's currency. Equals
amountInInvoiceCurrencywhen both currencies are the same. -
paymentDatestring · daterequiredDate the payment is registered on
-
feesInBankCurrencyinteger · int64requiredBank fees booked with this payment, in minor units of the bank account's currency; 0 when there are none
-
-
-
clearingDatestring · dateDate to register every payment on, instead of the bank transaction date. When given, it replaces the
paymentDateof every allocation item. Use it to clear into an open period when the bank transaction date falls in a closed one.
Response
-
accountingDocumentsarray of objectThe documents in the preview, with what is still open on each
-
idstring · uuidID of the accounting document
-
documentTypestringDocument type:
ARfor an invoice receivable,APfor an invoice payable⚠️ This enum is not exhaustive; new values may be added in the future.
One of
APARBPCCCNCTDEFXJEYC -
currencystringCurrency of the document
-
outstandingBalanceinteger · int64Gross amount still open on the document, in minor units of its currency
-
withholdingobjectNull when the document has no withholding tax
-
remainingToPayinteger · int64Cash the document still expects: its gross still open, less the withholding that covers the rest. Payments are allocated against this amount, not
outstandingBalance. -
unavailableReasonstringWhy this payment realizes none of the document's withholding, when it can't. The document then expects its whole open gross in cash, and
remainingToPaysays 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
-
-
-
allocationobjectHow 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.
-
itemsarray of objectrequiredOne item per payment to register against a document
-
accountingDocumentIdstring · uuidrequiredID of the invoice receivable (AR) or invoice payable (AP) the payment clears
-
amountInInvoiceCurrencyinteger · int64requiredAmount the payment clears, in minor units of the invoice's currency
-
amountInBankCurrencyinteger · int64requiredAmount taken from the bank transactions, in minor units of the bank account's currency. Equals
amountInInvoiceCurrencywhen both currencies are the same. -
paymentDatestring · daterequiredDate the payment is registered on
-
feesInBankCurrencyinteger · int64requiredBank fees booked with this payment, in minor units of the bank account's currency; 0 when there are none
-
-
-
summaryobjectTotals of the allocation, and whether clear-and-reconcile would accept it
-
currencystringCurrency of the bank account; every amount in the summary is in its minor units
-
availableAmountinteger · int64Total of the bank transactions
-
allocatedAmountinteger · int64Total the allocation takes from the bank transactions
-
feesinteger · int64Total bank fees in the allocation
-
withheldAmountinteger · int64Withholding the allocated payments realize, which settles the documents on top of the cash
-
remainingBalanceinteger · int64Amount of the bank transactions left unallocated. Must be zero for a valid match. For invoices receivable it is
availableAmountplusfeeslessallocatedAmount, since fees were taken from what the customer paid; for invoices payable it isavailableAmountlessallocatedAmountandfees, since the bank charged them on top. -
isValidbooleanWhether clear-and-reconcile would accept this allocation. It is false when any of these holds:
remainingBalanceis not zero; the items of one document add up, inamountInInvoiceCurrency, to more than the document still takes, which is itswithholding.remainingToPaywhen it has withholding and itsoutstandingBalanceotherwise; a document that still takes a payment has no allocation item; an item paying a bill has anamountInInvoiceCurrencyoramountInBankCurrencythat is zero or negative, a negativefeesInBankCurrency, or two amounts that differ although the bill and the bank account have the same currency; a document'swithholding.unavailableReasonis set. The checks on a single item's amounts run for bills only; the preview doesn't check them on an invoice item.
-