Set aside collected invoice tax

When a customer payment is linked to a saved bank deposit, Oatmilk can suggest the invoice's sales-tax portion for a separate reserve account. An invoice marked paid without a linked bank receipt does not qualify. Reserving cash does not calculate the final tax liability, pay a tax authority or file a return.

Set up the accounts

Read taxReserves.overview for the current settings, available accounts and provider blockers. An administrator saves a route from the account receiving payments to a separate active bank account in the same currency with taxReserves.settings.save. Read the current settings revision first, preserve unchanged routes and choices, and supply that revision and an idempotency key when saving. A tracked account can be added with accounts.create; this does not open an account at a bank.

Reminder emails and automatic transfers are separate choices. Automatic movement starts off and needs an interactive administrator in the web app or an authorized MCP connection, with a supported, verified Wise connection and eligible accounts. The public API can read suggestions and manage permitted settings and manual records; it cannot authorize automatic money movement or send money. A bank connection that reads statements only supports suggestions and manual-transfer recording.

Turning automatic transfers on applies to newly received eligible funds. It does not silently send the older suggestion queue. Turning it off stops new automatic sends; a movement the bank already accepted may still finish.

When receipt evidence cannot establish that the money arrived after automatic setup, the suggestion explains its timing blocker. The administrator can still review and move an otherwise eligible reserve explicitly.

Review a suggestion

Use taxReserves.overview to find the suggestion, then taxReserves.get to inspect its exact invoice, linked payment and bank receipt, currency, source and destination account identities, status and cumulative calculation. Partial payments reserve proportional recorded tax, with cumulative rounding capped at the invoice's tax. Duplicate receipt processing does not create another reserve.

Missing accounts, ambiguous or changed evidence, reversed payments, fee-netted receipts and unsupported currency conversions require review. A bank nickname or an account balance does not prove that an invoice was paid. Refunds and later corrections may require an adjustment; Oatmilk does not silently pull money back from the tax account.

Move or record money

After the administrator reviews the exact amount and accounts in an interactive web or MCP connection, taxReserves.transfer requires the current suggestion revision and its unchanged reviewedSnapshot. The server checks the evidence, account route, provider access and available balance again. Preserve the exact input and idempotency key if the request outcome is uncertain; never send a new transfer just because a response timed out.

For unsupported banks, move the money in the bank first. taxReserves.recordTransfer records the actual date and reference with the current revision and snapshot. This saves the administrator's statement of a completed manual transfer; it does not send money or independently prove bank completion. An uncertain in-flight provider request needs reconciliation before it can be resolved.

Suggested, checking, provider-confirmed and manually recorded transfers are distinct outcomes. Always report the returned status and blockers. taxReserves.dismiss leaves out an unpaid suggestion with an audited reason; it does not refund or reverse money.

If invoice tax or receipt evidence changes after money moved, taxReserves.get separates the retained amount already moved, the current target and any bank return still needed. taxReserves.acknowledge saves the administrator's review with a reason and fresh snapshot. A shortfall becomes a manual top-up suggestion. To reconcile excess cash already returned, supply the exact amount, actual reference and date, and both saved bank rows: a debit from the tax account and credit to the receiving account. This action never moves money back automatically.

Use the same flow in an AI app or terminal

Select the budgets MCP toolset. The oatmilk_review_tax_reserve card shows the same financial review and offers one explicit confirmation when permitted. Plain-text clients use accounting_tax_reserves_get and show the complete review before asking for approval. Ask AI and the terminal use the same actions, current revisions, calculation and permission checks.

In the terminal, open Budgets and choose Tax reserves. Account setup, reminders, automatic-transfer settings, individual reviews and completed manual-transfer recording stay in the terminal. Headless clients can use the shared action catalog and machine-readable results.