VAT Filing models

What this domain is

Models in scope: two (VAT_INVOICES, VAT_TAX_CODES). The group also contains two VAT_Codes sibling models, which are out of scope for this document.

VAT Filing exposes the transaction-level data behind Sovos's periodic VAT reporting and filing product. VAT_INVOICES is the tax-line backbone used to prepare VAT returns, EC Sales Lists, Intrastat, and MOSS/OSS declarations. VAT_TAX_CODES is the tax-code master that classifies each code and tells you which returns it feeds.

The two models and how they relate


Model	Grain (one row =)	Use it for
`VAT_INVOICES`	one VAT transaction line (a tax-relevant debit/credit posting)	VAT-return figures, net/VAT/gross by period, counterpart and country analysis
`VAT_TAX_CODES`	one Sovos VAT code (master)	interpreting/classifying tax codes; which report each feeds

CODE

VAT_INVOICES.TaxCode ──▶ VAT_TAX_CODES.InternalVatCode (many transaction lines → one tax code)

VAT_INVOICES.TaxCode ──▶ VAT_TAX_CODES.InternalVatCode (many transaction lines → one tax code)

Direction: On VAT_INVOICES, direction is derived from the tax code's IsOutgoing flag: outgoing means sales, incoming means purchase.
Cross-domain: CompanyId (SDA company id) links to CN, SAF-T, and Intelligence.

Practical notes for VAT

Amounts are signed (debit minus credit): NetTotal, VatTotal, and GrossTotal can legitimately be negative (credits, corrections, reversals).
VAT_INVOICES is a wide model (~120 columns). Which columns are populated depends on the country and source ERP. The tax rate is best taken from VAT_TAX_CODES or the tax-code description.
VAT_TAX_CODES carries authored, per-field descriptions, so use it as the authoritative reference for tax-code meaning. Exclude inactive codes (IsActive = FALSE) from new analysis.

VAT_INVOICES

Variant name: VAT_INVOICES. modelName "VAT Filing". modelGroupId 29b423ea-.. Version 5.
Grain: One row = one VAT transaction line (the VAT Filing transaction data row). A single tax-relevant posting within an invoice, enriched with tax-code and country master data.
Purpose: The transactional backbone of Sovos VAT Filing. Each row is a debit/credit tax line with derived direction, counterpart resolution, net/VAT/gross totals, tax-code classification, currency and secondary-currency amounts, Intrastat/Extrastat statistics, ERP references, and up to seven free-form purchase-extra fields. Used for VAT return preparation, period reporting, and reconciliation.

Field families are grouped for brevity. Every projected field is listed.


Field	Type	Description	Example values / notes
Direction	VARCHAR	Derived from v.ISOUTGOING; falls back to VATCODE-vs-country pattern.	`Inbound`, `Outbound`
Country	VARCHAR(300)	UPPER(t.COUNTRY).	`RO`
CompanyCode	-	t.COMPANYCODE.
DocumentType	VARCHAR(16MB)	t.DOCUMENTTYPE.
InvoiceNumber	-	t.INVOICENUMBER.
InvoiceDate	DATE	CAST(t.INVOICEDATE).	`2025-10-14`, `2025-12-05`
ReportingDate	DATE	CAST(t.REPORTDATE).	period assignment date
ReferenceId	-	t.REFERENCEID.
OriginalInvoiceNumber	-	Corrected/original invoice ref.	credit-note linkage
AdditionalDocumentReference	-	t.ADDITIONALDOCUMENTREFERENCE.
ErpDocument	-	t.ERPDOCUMENT.
InvoiceCorrectionType	-	t.INVOICECORRECTIONTYPE.
CreditIndicator	-	t.CREDITINDICATOR.
IssuerId	-	t.ISSUERID.
OperationType / TransactionCode / TransactionType	-	Operation/transaction classifiers.
SalesBookSequentialNumber / PurchaseBookSequentialNumber	-	Ledger book sequence numbers.
CounterpartName	-	Derived: customer or supplier name per direction.
CounterpartRegistrationNumber	-	Derived: customer/supplier VAT number per direction.
CustomerId / CustomerName / CustomerVatNumber / CustomerCountryVatNumber / CustomerDeliveryId	-	Customer party family.
CustomerBillToStreet / City / Region / PostalCode / Country	-	Customer bill-to address family.
SupplierId / SupplierName / SupplierVatNumber / SupplierCountryVatNumber / SupplierLocalTaxNumber	-	Supplier party family.
SupplierBillToStreet / City / Region / PostalCode / Country	-	Supplier bill-to address family.
TransactionDate / CustomerDeliveryDate / SupplierDeliveryDate / GlPostingDate / UtilizationDate / IntrastatDate	DATE	Various transaction/delivery/posting dates (CAST to DATE).	date family
FiscalYear / FiscalPeriod / ErpFiscalYear / ErpFiscalPeriod	-	Sovos + ERP fiscal period.	period keys
GrossTotal	NUMBER	(TaxableBasisDebit−Credit)+(VatDebit−Credit).	1722, -3188.16, 3099.6
NetTotal	NUMBER(38,8)	TaxableBasisDebit − TaxableBasisCredit.	1400, -900, -2592
VatTotal	NUMBER(38,8)	ValueVatDebit − ValueVatCredit.	322, -207, -596.16
TaxableBasisCredit / TaxableBasisDebit	-	Raw net debit/credit components.	measures
ValueVatCredit / ValueVatDebit	-	Raw VAT debit/credit components.	measures
TotalValueLine	-	t.TOTALVALUELINE (line gross).	measure
CurrencyCode	VARCHAR	t.CURRENCY.
ExchangeRate	-	t.EXCHANGERATE.
CurrencyCode2 / TaxableBasisCurrency2 / ValueVatCurrency2 / CommercialValueCurrency2 / TotalValue2	-	Secondary-currency amounts family.	dual-currency reporting
TaxCode	VARCHAR(16MB)	t.VATCODE — join key to VAT_TAX_CODES.InternalVatCode.	`RO110001`, `RO130001`, `RO130501`
TaxCodeDescription	VARCHAR(500)	v.DESCRIPTION (from the VAT-code master).	e.g. `RO110001-Purchase-I-SR-Domestic purchase of trade goods`
TaxRate	NUMBER(38,0)	Normalized rate: SOCSECVATRATE ×100 if ≤1, rounded.
OriginalTaxRateApplied	-	t.ORIGINALTAXRATEAPPLIED.
OriginalTaxCode / OriginalTaxCodeDescription	-	Original VAT code + desc before substitution.
TransactionKey	—	t.VATCODEACCOUNTINGKEY.
ChargeType	VARCHAR(14)	ISORIGINAL=TRUE→`Standard` else `Reverse Charge`.	`Standard`
InvoiceLineNumber	-	t.INVOICELINENUMBER.
ItemCode / ItemDescription / AdditionalDescription / GlDescription / AdGestionaliText	-	Item + description family.
PlantCode / Uom / DeliveryConditions	-	Logistics attributes.
IntrastatCode / ExtrastatCode / StatisticalProcedure / StatisticalValue / Weight / Quantity / ModeOfTransport / CustomsNumber	-	Intrastat/Extrastat statistics family.
CountryOrigin / CountryArrival / CountryDispatch / RegionArrival / RegionDispatch	-	Movement geography family.
BusinessArea	-	t.BUSINESSAREA.
GeneralLedgerId	-	t.GENERALLEDGERID.
TransactionId	-	t.TRANSACTION_ID.	row business id
AdministrationId / BatchId / AccountId	-	Administration / batch / account ids.	join/grouping keys
PurchaseExtra1-7	-	Seven free-form purchase-extra fields.	customer-specific extension
SourceCompanyId	-	t.COMPANYCODE.	↔ CN SourceCompanyCode
CompanyId	-	t.SDA_COMPANY_ID.	primary cross-domain join key
DataSource	-	t.SDA_DATASOURCE.

Keys vs attributes vs measures: Keys: TransactionId, CompanyId (SDA_COMPANY_ID), SourceCompanyId, AdministrationId/BatchId/AccountId, TaxCode. Measures: GrossTotal, NetTotal, VatTotal, TaxableBasis*, ValueVat*, TotalValueLine, *Currency2 amounts, StatisticalValue, Weight, Quantity, TaxRate, ExchangeRate. Rest attributes.
Joins: TaxCode ↔ VAT_TAX_CODES.InternalVatCode (tax-code lookup for direction, description, and rate type). CompanyId (SDA_COMPANY_ID) links to the CN models and Intelligence INVOICES. SourceCompanyId ↔ CN SourceCompanyCode.
Notes: Debit/credit design: totals are signed (Debit minus Credit), so negatives are legitimate (credit lines or reversals). Direction, CounterpartName, and CounterpartRegistrationNumber depend on ISOUTGOING from the tax code. When NULL, a VATCODE-pattern heuristic (code starts/ends with country) is used, and this can be NULL if neither matches. Very wide (~120 columns), so most fields' business meaning comes only from the column name.

VAT_TAX_CODES

Variant name: VAT_TAX_CODES. modelName "VAT Filing". modelGroupId 318ebd82-.. Version 4. Only model with authored descriptions.
Grain: One row = one Sovos VAT code (tax-code master).
Purpose (authored): Canonical VAT-code master for VAT Filing analytics. Interprets tax codes used on transaction lines, classifies them by jurisdiction and rate type, and flags which periodic reports each code feeds (VAT return, ESL, Intrastat, MOSS). Use as a lookup against VAT_INVOICES.TaxCode.


Field	Type	Description	Example values / notes
InternalVatCode	VARCHAR	Internal Sovos VAT code; primary join key from VAT_INVOICES.TaxCode. Exposed as stable text.	`LT140200`, `BE141060`, `999999CZ`
Description	VARCHAR(500)	Human-readable VAT-code description from tax-engine master.	`MT195001-Purchase-N-SR-Domestic purchase.`
VatRateType	VARCHAR(10)	Rate type classification (standard/reduced/zero/exempt).	`SR` (standard), `OS`
CountryCode	VARCHAR(2)	ISO country of jurisdiction; NULL when no country assigned.	`LT`, `MT`, `BE`, `HU`, `CZ`
CountryName	VARCHAR(255)	Full country name; NULL when no country.	`Lithuania`, `Malta`, `Belgium`
IsEuCountry	BOOLEAN	TRUE if assigned country is EU member; NULL when no country.	`true`
IsOutgoing	BOOLEAN	TRUE=sales/output code, FALSE=purchase/input. Primary direction signal for VAT_INVOICES.Direction.	`true`/`false` mix
IsActive	BOOLEAN	Whether code is currently usable (inactive kept for history).	`true`; `false` for CZ999999/999999CZ
SalesLedger	BOOLEAN	Eligible to post on sales ledger.	mix
PurchaseLedger	BOOLEAN	Eligible to post on purchase ledger.	mix
EuReport	BOOLEAN	Feeds EU-level VAT reporting (beyond ESL/Intrastat).	mix
EslGoods	BOOLEAN	Feeds EC Sales List — goods.
EslServices	BOOLEAN	Feeds EC Sales List — services.
IntrastatArrival	BOOLEAN	Feeds Intrastat arrivals (intra-EU acquisitions).
IntrastatDispatch	BOOLEAN	Feeds Intrastat dispatches (intra-EU supplies).
Moss	BOOLEAN	Feeds MOSS/OSS return (cross-border B2C).	`false` mostly, `true` for MT195001
ExemptReasonCode	-	Legal exemption reason when code is an exempt supply.

Keys vs attributes vs measures: Key: InternalVatCode (unique per row). No measures, this is a pure master/dimension. All other fields are classification attributes or flags.
Joins: InternalVatCode ↔ VAT_INVOICES.TaxCode (many transactions → one code). CountryCode joins to country masters or other country-keyed models.
Notes: CountryCode, CountryName, and IsEuCountry are NULL when a code has no country assigned. Direction and ledger flags drive VAT_INVOICES derivations. Inconsistent flags exist in the data, for example IsOutgoing TRUE but description says Purchase as in LT140200 and MT195001. Some codes are reversed strings (999999CZ vs CZ999999) representing sale vs purchase. Inactive codes (IsActive=FALSE) should not be applied to new postings.

Data and Analytics