VAT return and accounting 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.

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:

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

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:

{ "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

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

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.