Return forms and boxes
Define the boxes of your VAT return and what fills each one.
Before you begin
- You have tax.configure; a different administrator activates the form.
- You have your tax specialist's list of return boxes. The system does not ship an approved UAE form.
What a return form is
A return form lists the boxes of the return. Each box says which documents fill it. When a return is prepared, every posted taxable line is sent to the boxes that match. Nobody types a box amount.
Steps
- Choose Tax > Configuration > Return forms and boxes.
- Press New.
- Fill the common fields: Code (for example
AE-VAT201), Name, Country, Valid from. - Choose the Tax (VAT). It must match the registration's tax.
- Type the Form version (default 1).
- Set Ledger difference that may stand unexplained from 0 to 1,000 AED (default 0).
- Write the Boxes (JSON) list (see below).
- Save. A second administrator presses Activate.
What a box says
Each box entry has:
| Part | Meaning |
|---|---|
box | The box number, unique, for example 1a |
label, arabic | The box text |
measure | net, tax, recoverable or net_payable |
side | sale, purchase or both |
treatments | List: standard, zero, exempt, out_of_scope, reverse_charge |
tax_codes | Optional list of tax codes |
place_of_supply | Optional emirate or region code such as AUH or DXB |
reverse_charge | true, false or empty |
sign | 1 or -1 |
Example of one box: standard-rated supplies in Abu Dhabi, measured by net amount.
[{"box":"1a","label":"Standard rated supplies Abu Dhabi","measure":"net","side":"sale","treatments":["standard"],"place_of_supply":"AUH"}]
With boxes 1a (standard, AUH), 1b (standard, DXB), 2 (zero rated) and 3 (exempt), an AUH invoice net lands only in 1a and a DXB invoice only in 1b.
What happens next
When someone creates a return, the form must be active and match the registration's country and tax. Credit notes land in the same boxes with negative amounts.
Refusals
| Situation | Message |
|---|---|
| No boxes at activation | 'A return form needs its boxes.' |
| Not a JSON list | 'Boxes are a JSON list.' |
| Duplicate box number | 'Box 2 needs its own box number.' |
| Bad measure | 'Box 1a: measure is one of net, tax, recoverable, net_payable.' |
| Unknown treatment | 'Box 1a: unknown treatment vat.' |
| Bad sign | 'Box 1a: sign is 1 or -1.' |
| Tolerance above 1,000 | 'Choose between 0 and 1000.' |
| Wrong country form | '<FORM> is a SA vat form; the registration is AE vat.' |
Good to know
- A form with a tolerance of 0 requires the return to match the tax accounts exactly before approval. A higher tolerance lets a small difference stand; explain larger ones.
- To change an active form, archive it and create a new version.
- Conditions and boxes are typed as JSON. Ask your tax specialist to review them before activation.
- The cash-rounding line of an invoice is not a supply and is not on the return.