# VAT return and accounting exports

> Tax rates, the VAT 201 worksheet, saved returns and import files for Zoho Books, Xero, QuickBooks Online and Tally.

Source: /docs/guides/vat-and-exports

## Tax rates

Every organization has one rate per UAE VAT category, created on first use. Rates carry the default exemption reason (BT-121 code, BT-120 text) written into the XML tax breakdown for non-standard categories.

```bash
curl "$BASE/settings/tax-rates" -H "X-API-KEY: $KEY"
curl -X POST "$BASE/settings/tax-rates" -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{ "category": "zero_rated", "name": "Zero rated – export of goods", "exemptionReasonCode": "VATEX-AE-EXPORT", "exemptionReason": "Export of goods outside the GCC" }'
```

Invoice lines accept `taxExemptionReasonCode` and `taxExemptionReason`; when omitted, the rate's default (or a built-in text per category) is used. The standard category never carries a reason.

## VAT 201 worksheet

`GET /vat/worksheet?from=2027-01-01&to=2027-03-31` (or `?date=2027-02-15` to pick the organization's tax period containing that date) returns the boxes of the UAE VAT return:

| Box | Source |
| --- | --- |
| 1a–1g | Standard-rated lines of issued invoices (`submitted`, `delivered`, `accepted`; not test, not archived), per emirate. The invoice's `supplyEmirate` wins; otherwise the organization's emirate. Credit notes are negative. Document allowances and charges are included. |
| 2, 6, 7 | Manual figures (tourist refunds, imports, import adjustments) taken from the saved return of the period. |
| 3, 10 | Reverse-charge lines of accepted incoming invoices, VAT at the standard rate. |
| 4, 5 | Zero-rated and exempt lines of issued invoices. |
| 9 | Standard-rated lines of accepted incoming invoices with their VAT. |
| 8, 11, 12, 13, 14 | Computed totals and net VAT (`totals.netVat`, `totals.payable`). |

Each box carries `amount`, `vat`, `adjustmentAmount`, `adjustmentVat`, `source` and `documents`. `info` lists reverse-charge and out-of-scope sales that are shown but not reported. `format=csv` returns the worksheet as CSV. Tax is computed per invoice and category exactly as on the documents (taxable amount rounded, then multiplied by the rate).

Documents in another currency are converted to AED at their own exchange rate, per invoice and category (taxable and VAT each rounded to fils). A rate of exactly 1 on a non-AED document (the former default) is ignored in favour of the stored UAE Central Bank rate for the document's date. Documents with no usable rate are left out of the boxes and listed in `info.unconverted.sales` / `info.unconverted.purchases` (`id`, `number`, `currency`, `date`); fetch their rates or set one on the document and request the worksheet again.

`GET /vat/periods` lists recent periods with filing due dates and the status of the saved return; the period settings (`months` 1 or 3, `startMonth`, `dueDays`) live on the organization.

## Saved returns

```bash
curl -X POST "$BASE/vat/returns" -H "X-API-KEY: $KEY" -H "Content-Type: application/json" -d '{
  "periodStart": "2027-01-01", "periodEnd": "2027-03-31", "status": "filed", "reference": "EMT-2027-Q1-0042",
  "manual": { "importsAmount": 12000, "importsVat": 600, "adjustments": { "1b": { "amount": -500, "vat": -25 } } }
}'
```

One return per period (upsert). Saving recomputes the worksheet and stores it in `figures`; `status: "filed"` records `filedAt`, keeps the figures in `filedFigures` and **locks the period**. `GET /vat/returns`, `GET /vat/returns/{id}`, `DELETE` (drafts only).

## Locked periods

A filed return locks its period, and the organization can set lock dates (`lockDateAll`, `lockDateNonAdmin` in `GET/PATCH /settings/options`). Creating, changing or deleting an invoice, credit or debit note (issue date or date of supply), an accepted incoming invoice, or a payment (lock dates only) dated in a locked period returns `409 period_locked`:

```json
{ "code": "period_locked", "statusCode": 409, "message": "Invoice INV-0042 is dated 2027-02-15, in the VAT period 2027-01-01 to 2027-03-31, whose VAT return is filed. Use a date on or after 2027-04-01, or ask an owner or admin to reopen the return.",
  "extra": { "lockSource": "vat_return_filed", "periodStart": "2027-01-01", "periodEnd": "2027-03-31", "vatReturnId": "…", "firstOpenDate": "2027-04-01" } }
```

Submitting or sending a draft dated in a locked period returns the same error. Received documents are never refused; an incoming invoice accepted after its period was locked counts in the first open period (`vatRecoveryDate`).

- `GET /vat/check-date?date=2027-02-15`: lock state of a date for your key (`locked`, `blocked`, `lockSource`, `firstOpenDate`).
- `GET /vat/periods`: each period has `locked` and `lockSource`; the response adds `lockDates` and `fiscalYear`.
- `POST /vat/returns/{id}/reopen` with `{ "reason": "…", "acknowledgeVoluntaryDisclosure": true }` reopens a filed return (409 `lock_date_covers_period` while `lockDateAll` covers it).
- The `periods:manage` scope is needed to reopen, to change lock dates, and to pass `lockDateNonAdmin`.
- Webhooks: `vat_return.filed`, `vat_return.reopened`, `lock_date.changed`.

## Accounting exports

```bash
curl "$BASE/exports/accounting?system=xero&kind=sales&from=2027-01-01&to=2027-03-31&taxCode.standard=5%25%20VAT%20on%20Income&accountCode=200" \
  -H "X-API-KEY: $KEY" -o sales-q1.csv
curl "$BASE/exports/accounting?system=tally&kind=purchases&date=2027-02-01" -H "X-API-KEY: $KEY" -o purchases.xml
```

| `system` | Format | Layout |
| --- | --- | --- |
| `zoho` | CSV | Zoho Books invoice / bill import, one row per line, place of supply, TRN, project name |
| `xero` | CSV | Xero sales invoice / bill template (`*ContactName`, `*InvoiceNumber`, `*AccountCode`, `*TaxType`, …), project as tracking option |
| `quickbooks` | CSV | QuickBooks Online invoice / bill import (`*InvoiceNo`, `*Item(Product/Service)`, `*ItemTaxCode`, …) |
| `tally` | XML | Tally `Import Data` envelope with Sales / Purchase / Credit Note / Debit Note vouchers, party ledger, per-category sales or purchase ledger, VAT ledger |

`kind=sales` exports issued invoices (credit notes negative); `kind=purchases` exports accepted incoming invoices. Override tax code labels with `taxCode.<category>=`, the income/expense account or ledger with `accountCode`, the Tally VAT ledger with `vatLedger`. `format=json` wraps the file in `{ filename, mime, content }` for MCP clients. `GET /exports/accounting/systems` lists the systems with their default tax codes.

## MCP and CLI

Tools: `list_tax_rates`, `create_tax_rate`, `update_tax_rate`, `list_vat_periods`, `get_vat_worksheet`, `list_vat_returns`, `save_vat_return`, `reopen_vat_return`, `check_period_date`, `export_accounting`. CLI: `alyabooks vat worksheet --from … --to … [--csv -o file]`, `alyabooks vat save --from … --to … --filed --reference …`, `alyabooks export accounting --system xero --kind sales --from … --to … -o file`, `alyabooks tax-rate list`.

See also the [rounding reference](/docs/reference/rounding).