ZuloOne
English
CabinetAccount
Sign in
Menu

🧾 Tax return and payment

Updated

← Business process wiki

How the process works#

Posted TaxLedger movements are collected into a TaxReturn, the return is filed through an authority submission service, every filing attempt writes TaxSubmission, and TaxPayment posts the settlement to the general ledger. The country-neutral core ships a mock authority service (accept or reject from setup data); there is no live HTTP exchange to a tax authority in core.

The sequence is:

  1. Source documents create TaxCalculation and TaxLedger movements.
  2. A named TaxPeriod defines the legal entity, tax, and inclusive date window.
  3. The Build return command on the TaxPeriod creates a draft TaxReturn.
  4. The File tax return command moves the return to Filed and calls the mock tax authority service.
  5. A separate TaxPayment is created and posted with Pay tax. It does not change the return and does not change TaxLedger; it posts Dr VAT payable / Cr cash in the general ledger when the legal entity and accounts are configured.

Payment is always a separate document. Do not model a paid return by moving the return again: Filed is the frozen document that was submitted.

Settings#

Tax periods#

Open Ribbon → Tax → Dictionaries → Tax periods.

Field Values and behaviour
Legal entity Required. Only TaxLedger movements for this legal entity enter the return.
Tax Required. Names the tax that the period is for. The current builder filters by legal entity and dates; use one period per tax so the return name and mappings stay clear.
Code Required short identifier, for example VAT-2026-01. The command message uses it.
Name Optional display text. Empty is valid.
From / To Required inclusive dates. 2026-01-01 through 2026-01-31 includes movements on 31 January.
Closed Empty or off means the period may build a new return. On means Build return refuses the period.

Default: a new period is open. Closing a period blocks new returns for that named period and also blocks a raw-date build that overlaps a closed period of the same legal entity. It is not the same as an accounting FiscalPeriod: the accounting period controls whether documents can post at all.

Return mappings#

Open Ribbon → Tax → Dictionaries → Return mappings.

Field Values and behaviour
Tax Required. The tax whose codes are mapped.
Tax code Required. A line in the return is mapped by the code found in TaxLedger.
Direction Optional. Empty means any direction. A directed row, such as OUTPUT or INPUT, wins over an undirected row for the same code.
Return type Required text, for example VAT-SA or a country package form code. Core stores it but does not choose a country from it. The Saudi package seeds six VAT-SA rows; the Ukrainian package seeds form J0200126.
Return box Required cell name, up to 32 characters. This value is copied to the TaxReturn line.
Effective from / Effective to Required start and optional end. Empty end means open-ended. The return uses the row effective on the period end date.

If two country packages map the same (tax code, direction) to different boxes for the same period end date, core leaves Return box empty instead of guessing the country. Fix the mappings or use the country-specific return export.

Authority connection#

Open Ribbon → Tax → Settings → Authority connections.

The connection is looked up by Legal entity. Empty connection means the mock still writes a TaxSubmission row, with an empty authority and connection code. Set Is mock reject on the connection when you need to test a rejected filing; the return or payment remains posted and the rejection is visible in Authority submissions.

GL account profile#

Open Ribbon → Accounting → Settings → Accounting settings.

For tax payment, the relevant references are:

Field Empty value Filled value
VAT payable account No VAT payable leg can be posted for tax payment. Debited by TaxPayment.
Cash account No cash leg can be posted for tax payment. Credited by TaxPayment.

The visible fields are references to ChartOfAccounts. On save, the hidden *AccountCode field is stamped from the selected account. An empty account leg skips GL posting; the tax payment document still moves to Paid.

Example with numbers#

A legal entity posts two January documents:

Source Direction Tax code Tax base Tax amount Recoverable amount
Sales realization OUTPUT VAT15 1,000.00 150.00 150.00
Purchase receipt INPUT VAT15 with 40% non-recoverable 600.00 90.00 54.00

The January TaxReturn header is:

Header field Amount
Output tax 150.00
Input tax 54.00
Net payable 96.00

The return lines show one output line for 150.00 and one input line for 54.00. If Return mappings map VAT15 + OUTPUT to box A1 and VAT15 + INPUT to box B1, those boxes are copied to the lines.

A TaxPayment for 96.00 posts Dr VAT payable account 96.00 / Cr Cash account 96.00. It does not reduce the TaxLedger; the ledger stays the filing evidence.

Boundaries and edge cases#

  • Build return creates a new draft return. It is intentionally on TaxPeriod, not on TaxReturn, because the return does not exist yet.
  • A closed TaxPeriod refuses building a return. A closed FiscalPeriod refuses document posting for its date and therefore stops new tax movements before the return is built.
  • The return groups by TaxCode and TaxDirection. It does not store source invoice numbers or payment allocation.
  • Input tax uses Recoverable amount in the return. Non-recoverable input VAT has already been added to stock cost and GL by the purchase process.
  • Mock authority rejection writes a TaxSubmission row and does not roll the return or payment back.

What is posted#

Document and transition Register or ledger movement
Source tax calculation → Finalized TaxLedger: TaxBase, TaxAmount, RecoverableAmount by tax code, direction, and legal entity.
TaxReturn → Filed No register movement. Calls the authority submission service and writes TaxSubmission.
TaxPayment → Paid No tax register movement. GL posts Dr VAT payable / Cr cash when the payment has a legal entity and accounts.

What's not there yet#

  • The country-neutral core has no live HTTP to the tax authority. The delivered service is a mock and writes MOCK-OK or MOCK-REJECT receipts.
  • Core return boxes are generic strings. Official country forms and electronic files belong to localization packages: the Saudi package ships the VAT-SA box layout and an Export for filing sheet in SaTaxFilingExport (Saudi localization), the Ukrainian package ships form J0200126 and a neutral filing export.
  • There is no open-item tax-payment matching. A payment line reduces the GL liability; it is not allocated to one return number.
  • There is no bank account, cash desk, or bank reconciliation in this contour.

Same topic for other readers: User

Where next#

Was this page helpful?