Tax configuration field guide

Tax configuration determines how OSERP calculates, posts, reports, and explains tax. A tax code is a controlled rule, not merely a percentage. It needs legal company, jurisdiction, effective dates, transaction type, item or service category, customer/supplier status, recoverability, accounts, and evidence.

Tax code master

Open Finance → Tax Master → New.

Field	Example	Purpose and impact
Tax code	UAE-STD-5	Transaction and API key
Description	UAE standard VAT 5%	User explanation
Legal company	Demo Retail Group LLC	Statutory scope
Jurisdiction	UAE-DXB	Tax authority and return
Tax type	VAT / withholding	Calculation family
Rate	5.000%	Tax amount
Effective from	2026-01-01	Version boundary
Effective to	Blank	Future validity
Sales account	231100	Output-tax posting
Purchase account	141100	Input-tax posting
Recoverability	100% / partial	Deductible amount
Reporting box	VAT-01	Return mapping
Rounding	Line / document	Precision behavior
Active	Yes	Future selection

Never edit a rate used by posted documents. Create a new effective-dated version and preserve the prior rule. An inactive code remains visible in history.

Jurisdiction and transaction context

Jurisdiction fields include country, state/emirate, registration, authority, filing frequency, currency, tax calendar, and return owner. Transaction context includes legal company, tax date, supply location, ship-to, bill-to, item/service category, customer/supplier tax status, incoterm, and import/export flag.

For a UAE sale to a Dubai customer, UAE-STD-5 may apply. An export or exempt supply needs documented evidence and effective date. Tax defaults are suggestions; transaction date and legal entity remain authoritative.

Item and partner tax defaults

Item tax detail stores category, HSN/SAC or local code, sales code, purchase code, exemption, effective dates, and evidence. Partner tax detail stores registration, category, exemption certificate, reverse-charge flag, withholding class, and jurisdiction.

If a certificate expires on 30 September, an invoice dated 1 October should use the default rule or create an exception. Do not hide expiry in a note. A manual override needs permission, reason, certificate, and audit event.

Calculation and rounding

For net AED 9,690 at 5%, tax is AED 484.50 and total AED 10,174.50. OSERP should show taxable base, rate, tax amount, rounding difference, and calculation basis. Line-level and document-level rounding must be configured consistently with statutory requirements.

Tax-inclusive prices reverse-calculate the taxable base using the effective rate. A discount may reduce the base; freight or service charges may have different codes. Tax code and tax amount are not interchangeable fields.

Posting and accounts

Sales posting debits receivable and credits revenue plus output-tax account. Purchase posting debits expense, inventory, or asset plus input-tax account and credits payable. Non-recoverable input tax joins cost; recoverable input tax remains a tax asset.

Each tax line carries company, branch, partner, item/service, jurisdiction, return box, and source document. A manual journal to the tax account requires an adjustment reason and return owner.

Imports, exports, and reverse charge

Import fields include customs declaration, supplier country, import date, duty, tax paid at border, recoverability, and evidence. Export fields include destination, incoterm, transport proof, export declaration, and zero-rating reason. Reverse-charge fields include customer/supplier status, service location, tax code, and self-assessment reporting box.

An export without shipping evidence remains an exception. A reverse-charge transaction posts tax output and input according to policy; it is not simply zero tax.

Withholding tax

Withholding records partner, category, base, rate, authority, certificate, payment date, and payable account. On a supplier invoice, withholding reduces cash payable and creates authority liability. The certificate remains linked to invoice and payment.

Different legal entities may use different rates. Effective dates and jurisdiction must be validated before payment. A withheld amount cannot be treated as a supplier discount.

Returns and adjustments

The return workspace groups tax lines by code, jurisdiction, period, box, source, and status. It shows output, input, adjustments, reverse charge, withholding, and net payable/refundable. Every total drills to invoice, credit, purchase, journal, or customs evidence.

A tax adjustment records original period, current period, reason, authority reference, account, amount, and approval. A credit note reverses the original tax basis. Do not overwrite a posted return to make totals agree.

API and audit mapping

API payloads should include tax code ID, transaction date, legal company, jurisdiction, taxable amount, rate, tax amount, source, and exemption evidence. Use immutable version IDs and idempotency keys. Return calculation breakdown and reporting box.

{"taxCodeId":"uae_std_5_v3","companyId":"company_uae","taxDate":"2026-09-17",
 "taxableAmount":"9690.00","rate":"5.000","source":{"type":"AR_INVOICE","id":"ar_004281"},
 "exemption":{"applies":false}}

Audit evidence includes code version, input fields, calculation result, override, certificate, user, approval, source, request ID, and return status. Redact personal or bank data in support exports.

Reconciliation and practice

Reconcile tax subledger to sales and purchase invoices, credit notes, customs, withholding, journals, bank, and statutory return by company, jurisdiction, and period. Exceptions include missing code, expired certificate, tax mismatch, unreported adjustment, and posted transaction in locked period.

Practice: configure standard, zero, exempt, import, and withholding codes; create sales and purchase documents in two currencies; expire a certificate; post a credit note; prepare a return; and reconcile to GL. Explain every field’s owner, format/precision, effective date, permission, journal, return box, API ID, and evidence. Then attempt to use an expired exemption and edit a posted tax rate; prove both controls reject the action.

Related: AR Invoice field guide, AP Invoice field guide, Journal Entry field guide, Advanced GL Mapping, and API cookbook.