# Record an intercompany transfer

> Preview and save an advance or repayment against an existing bank transfer, with sources and a readback.

Source: https://app.getoatmilk.com/docs/tutorials/intercompany-transfers

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](https://app.getoatmilk.com/docs/api/tax.financialCounterparts.get.md) 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](https://app.getoatmilk.com/docs/api/tax.intercompanyCounterparties.list.md) to find the counterparty. Create a missing record with [tax.intercompanyCounterparties.create](https://app.getoatmilk.com/docs/api/tax.intercompanyCounterparties.create.md), 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](https://app.getoatmilk.com/docs/api/tax.intercompanyObligations.list.md), 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](https://app.getoatmilk.com/docs/api/tax.financialCounterparts.preview.md) 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](https://app.getoatmilk.com/docs/api/tax.financialCounterparts.review.md) 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](https://app.getoatmilk.com/docs/api/tax.reports.overview.md). 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](https://app.getoatmilk.com/docs/api/history.rollback.preview.md) to inspect a correction before [history.rollback.apply](https://app.getoatmilk.com/docs/api/history.rollback.apply.md).

Legacy untyped loans, shareholder balances and common shares retain their dashboard confirmation requirement. The explicit intercompany purposes above are available to authorized assistants.