Tutorials
Record an intercompany transfer
Preview and save an advance or repayment against an existing bank transfer, with sources and a readback.
An intercompany transfer can create a debt or settle one. Choose its purpose from the supporting records. A sender's name, transfer label or bank direction cannot establish income, expenses, equity or tax treatment.
This workflow completes the other side of an existing, fully matched CAD transfer. It preserves the imported cash movement and its original evidence. It currently supports CAD transfers in a CAD functional currency with no foreign exchange. Keep reimbursements, capital, fees and FX in their own supported workflows.
1. Inspect the existing transfer
Call tax.financialCounterparts.get with the imported entry's entryId. Check the current review first: a retry must not create a second cash movement or debt. The result includes the source, current entry and review revisions, original evidence, counterparty records and obligations. If the source is unsupported, changed or closed, resolve the reported problem before saving.
Inspect every page of the bank receipt and the relevant accountant instruction. Add a missing original through entries.evidence.prepare and entries.evidence.confirm, then read it before selecting it. Use the evidence IDs and hashes returned by Oatmilk, together with the current source fingerprints.
2. Choose the company and purpose
Use tax.intercompanyCounterparties.list to find the counterparty. Create a missing record with tax.intercompanyCounterparties.create, its legal name and an idempotency key. This record belongs to the current workspace; it grants no access to the other company's books and creates no entry there.
| Purpose | Cash entry already imported | Other side to record |
|---|---|---|
incoming_advance | Debit cash | Credit payable to the counterparty |
outgoing_advance | Credit cash | Debit receivable from the counterparty |
incoming_repayment | Debit cash | Credit an existing receivable |
outgoing_repayment | Credit cash | Debit an existing payable |
For a repayment, read tax.intercompanyObligations.list, filtered by counterpartyId. Supply the documented allocation as allocations, using each obligation's stable ID, current expectedRevision and exact amountMinor. Partial repayments leave a remaining balance. The server rejects an allocation above the available balance, the wrong counterparty or an incompatible obligation.
If the evidence does not establish the purpose or the debt being repaid, ask for that evidence before classifying.
3. Preview the accounting entries
Call tax.financialCounterparts.preview with entryId, purpose, counterpartyId, label, reason, selected evidence, sourceFingerprint, expectedEntryRevision, expectedRevision and the current supporting evidence fingerprint when applicable. Repayments also include their allocations.
Keep an accountant's documented instruction in instruction. Keep an owner's clarification separately in attestations: each statement has kind: "owner_attestation", the statement, attestedBy and attestedAt. An owner's statement that tax was paid is an attestation; it is not a verified tax return or payment receipt.
The preview shows the existing cash side and the counterpart side, with amounts, currency, counterparty and repayment balances. Review these consequences before saving. This classification records accounting facts; it does not guarantee tax compliance.
4. Save once and read it back
Send the same treatment to tax.financialCounterparts.review with confirmed: true and one stable idempotencyKey for the intended save. Reuse that key and identical payload after a network failure. A revised treatment needs a fresh key and the current revisions.
The dashboard, REST API, MCP and terminal app call the same posting service. On MCP, use accounting_tax_financial_counterparts_get, accounting_tax_financial_counterparts_preview and accounting_tax_financial_counterparts_review, passing the chosen organizationId. The companion tools are accounting_tax_intercompany_counterparties_list, accounting_tax_intercompany_counterparties_create and accounting_tax_intercompany_obligations_list. They are in the reports toolset. Finance or administrator access and the action's scopes are checked again on every operation.
A finished spinner is not proof of a save. Read tax.financialCounterparts.get again and confirm the returned review ID, revision, purpose, counterparty, evidence, instruction and attestations. The review must be current. Reload the financial report with the same accounting-date cutoff, using tax.reports.overview. Confirm the counterpart appears and that cash was not recorded again.
In the dashboard, reopen the original transfer in Finance Transactions. Its Transfer purpose section shows the saved treatment, accounting consequences, remaining debt and source details. Expand the evidence to distinguish originals from owner statements. Choose Review transfer purpose to reopen the same supported editor with the saved fields. Authorized finance and administrator read-only views can inspect the saved treatment; corrections still require the action's permissions, current versions and an open period.
Keep a failed request's draft and show its error. A version conflict requires a fresh inspect and preview; do not overwrite a newer review. If a response is lost, inspect the committed state before retrying.
Corrections and History
Corrections create a new review version. Earlier evidence and before/after state remain in History with the actor and time. tax.financialCounterparts.clear clears the counterpart through the same revision and source checks. An advance with active repayments must have those repayment allocations corrected first. Closed periods must follow the supported reopening process.
History's rollback preview checks the current source, review and obligation balances. A restored repayment uses the documented amounts with current obligation revisions, and is blocked if those amounts no longer fit. Use history.rollback.preview to inspect a correction before history.rollback.apply.
Legacy untyped loans, shareholder balances and common shares retain their dashboard confirmation requirement. The explicit intercompany purposes above are available to authorized assistants.