Compliance

OverviewCopy Anchor Link

Compliance endpoints help you monitor governed Article 59c distance-selling threshold evidence, validate individual consignments against IOSS limits, manage OSS/IOSS scheme registrations, preview Union OSS report outputs, review multi-jurisdiction filing exposure, and download accountant-facing export packages. The authenticated dashboard combines threshold evidence with tax-registration data to produce a conflict-aware, registration-aware OSS Overview. Threshold notifications use the same governed evidence and are withheld when required evidence is incomplete. Read endpoints require a V2 API key with full or read-only scope; write endpoints require full scope.

Tax Decision SourcesCopy Anchor Link

The authenticated Compliance → Decision Sources page shows the reviewed official sources and architecture boundaries for planned cross-platform tax reconciliation. It records the selected legal baseline, later amendments, effective intervals, scenario-specific evidence, known gaps, and shared review reasons.

For specified legal scenarios, the page shows each source's document kind and legal effect separately from supporting guidance, using ordered, gap-free source-coverage segments. When more than one legal source appears in a segment, every listed source must cover the whole segment and every provision and evidence signal shown; they are not interchangeable alternatives. Historical OSS, marketplace, and IOSS rows follow every published VAT Directive consolidation from 1 July 2021 through the current reviewed baseline. A consolidation is an official but non-binding compilation; the authentic acts published in the Official Journal are binding. Current Article 201 coverage ends on 30 June 2028, before its replacement applies. Source effective dates describe reviewed coverage for the listed provisions; they are not publication dates or a claim that every provision in a document applies throughout the interval.

The page also shows the source-review policy. Reviews must be renewed at least every 180 days and sooner when an upstream change is detected, an official authority issues a notice, or a rule-pack release is prepared.

“Specified” means that a scenario's source and architecture requirements are defined. It does not mean the automatic runtime rule is available. Optional or Member-State-dependent treatment stays visibly Unsupported until an approved national rule set exists. Commerce-platform fields are shown as source evidence, not as legal determinations.

OSS / IOSS Tax RegistrationsCopy Anchor Link

GET /v1/tax-registrations
POST /v1/tax-registrations
PATCH /v1/tax-registrations/{id}

Required scope: full or read-only for GET; full for POST and PATCH

Stores scheme-registration metadata for the authenticated account. Registration records are account-scoped, returned with masked identifiers only, and ordered by most recent effective window. Overlapping non-excluded effective windows for the same scheme are rejected.

Registration FieldsCopy Anchor Link

Reporting EligibilityCopy Anchor Link

Union OSS report previews require exactly one overlapping active or ended union_oss registration for the requested quarter. pending, excluded, and conflict-cleanup registrations are visible in registration management responses, but they do not satisfy report-preview eligibility.

Example RequestCopy Anchor Link

curl -X POST https://api.vat-engine.app/v1/tax-registrations \-H "X-API-Key: YOUR_API_KEY" \-H "Content-Type: application/json" \-d '{  "scheme_type": "union_oss",  "member_state_identification": "DE",  "effective_from": "2026-01-01",  "status": "active"}'

Union OSS Quarterly Summary PreviewCopy Anchor Link

GET /v1/reports/oss-quarterly-summary?period=YYYY-Qn

Required scope: full or read-only

Builds a read-only Union OSS quarterly summary preview from filing-grade vat_supply_events. The result is grouped into the Union OSS return sections 2a, 2b, 2c, and 2d.

Inclusion RulesCopy Anchor Link

• Requires exactly one overlapping active or ended union_oss registration for the requested quarter.
• Includes sale events as current-quarter return lines.
• Nets same-quarter corrections back into the current return lines when the refund, cancellation, credit note, or adjustment can be linked to the original filed supply.
• Emits later-period correction rows keyed by the original OSS period and Member State of consumption when the linked original supply falls in an earlier quarter.
• Excludes refunds, cancellations, credit notes, and adjustments that cannot be linked to an original filed supply event.
• Excludes source events whose classification_status is not classified, plus zero-rated, exempt, new-means-of-transport, and assembly/installation supplies.
• Uses ECB rates from the last day of the quarter when conversion is required, including the return currency of the Member State of identification.
• Keeps separate rows when more than one actual VAT rate applies within the same standard/reduced return grouping.
• Computes the payable grand total per Member State of consumption; a negative balance in one Member State does not offset VAT payable in another Member State.

Response FieldsCopy Anchor Link

Warning CodesCopy Anchor Link

Example RequestCopy Anchor Link

curl "https://api.vat-engine.app/v1/reports/oss-quarterly-summary?period=2026-Q1" \-H "X-API-Key: YOUR_API_KEY"

Union OSS Country VAT Breakdown PreviewCopy Anchor Link

GET /v1/reports/country-vat-breakdown?period=YYYY-Qn

Required scope: full or read-only

Builds a read-only country VAT breakdown using the same inclusion, exclusion, warning, and quarter-end ECB conversion rules as the Union OSS quarterly summary preview. The response groups totals first by Member State of consumption, preserves payable-per-country balances, and nests both current-quarter rows and later-period correction rows for that country.

Response FieldsCopy Anchor Link

Example RequestCopy Anchor Link

curl "https://api.vat-engine.app/v1/reports/country-vat-breakdown?period=2026-Q1" \-H "X-API-Key: YOUR_API_KEY"

Union OSS Accountant ExportsCopy Anchor Link

GET /v1/reports/oss-quarterly-summary/export?period=YYYY-Qn&format=csv|json
GET /v1/reports/country-vat-breakdown/export?period=YYYY-Qn&format=csv|json

Required scope: full or read-only

The European Commission states that OSS VAT returns are submitted quarterly in the Union scheme via the Member State of identification and are additional to domestic VAT returns. These endpoints export the current Union OSS preview state for accountant review; they do not create or lock a filed return.

Format BehaviorCopy Anchor Link

• format=json returns a manifest plus an export-specific report payload with the same grouping and warnings as the preview, but exported amounts use major-unit decimal strings in the return currency.
• format=csv returns a line-oriented CSV with manifest metadata repeated on each row, and all exported amount columns use major-unit decimal strings rather than _minor integers.
• Export packages now include current-quarter rows, later-period correction rows, and per-Member-State payable balances.
• When a quarter has no included rows, the CSV still emits a deterministic manifest-only nil-return row with empty detail fields so period and warning metadata are preserved.
• Both exports reuse the same registration eligibility, warnings, exclusions, and quarter-end ECB conversion rules as their source preview.

Amount FieldsCopy Anchor Link

All exported amount fields use major units in the return currency, for example 100.00 rather than 10000. This applies to both the JSON package payload and the CSV columns.

Rate FieldCopy Anchor Link

Export rows use the accountant-readable vat_rate_pct field, for example 20.00 or 7.00.

Manifest FieldsCopy Anchor Link

Example RequestsCopy Anchor Link

# Quarterly summary JSON packagecurl -L "https://api.vat-engine.app/v1/reports/oss-quarterly-summary/export?period=2026-Q1&format=json" -H "X-API-Key: YOUR_API_KEY"# Country breakdown CSV packagecurl -L "https://api.vat-engine.app/v1/reports/country-vat-breakdown/export?period=2026-Q1&format=csv" -H "X-API-Key: YOUR_API_KEY"

Locked Union OSS Return PeriodsCopy Anchor Link

GET /v1/reports/locked-return-periods/union-oss?period=YYYY-Qn
POST /v1/reports/locked-return-periods/union-oss?period=YYYY-Qn
POST /v1/reports/locked-return-periods/union-oss/filed?period=YYYY-Qn
GET /v1/reports/locked-return-periods/union-oss/exports/{exportID}

Required scope: full or read-only for GET; full for POST

These endpoints persist and retrieve immutable Union OSS filing snapshots. Locking a quarter freezes the current accountant preview, stores filing metadata, and generates immutable JSON and CSV artifacts for later download. Marking the period as filed preserves the original filing audit state rather than regenerating the snapshot.

BehaviorCopy Anchor Link

• GET /v1/reports/locked-return-periods/union-oss returns the latest locked quarters for the authenticated account.
• Supplying period=YYYY-Qn adds current_period when that quarter has already been locked, including the immutable export list for that specific quarter.
• POST /v1/reports/locked-return-periods/union-oss creates the immutable snapshot from the current preview and fails with 409 if the quarter is already locked.
• POST /v1/reports/locked-return-periods/union-oss/filed marks an existing locked quarter as filed and keeps the first filing audit metadata on repeat requests.
• GET /v1/reports/locked-return-periods/union-oss/exports/{exportID} downloads one stored artifact by ID.

Response FieldsCopy Anchor Link

Example RequestsCopy Anchor Link

# List recent locked quarterscurl "https://api.vat-engine.app/v1/reports/locked-return-periods/union-oss" -H "X-API-Key: YOUR_API_KEY"# Lock a quartercurl -X POST "https://api.vat-engine.app/v1/reports/locked-return-periods/union-oss?period=2026-Q1" -H "X-API-Key: YOUR_API_KEY"# Mark the locked quarter as filedcurl -X POST "https://api.vat-engine.app/v1/reports/locked-return-periods/union-oss/filed?period=2026-Q1" -H "X-API-Key: YOUR_API_KEY"

Union OSS Accountant FormatCopy Anchor Link

GET /v1/reports/oss-accountant-report?period=YYYY-Qn

Required scope: full or read-only

Returns a combined accountant-friendly Union OSS quarter view for review before filing. It reuses the same quarter preview rules as the summary and country-breakdown endpoints, exposes the export-safe major-unit amount strings and vat_rate_pct values, and includes later-period correction rows plus country-level payable balances in one JSON payload.

Filing Context RulesCopy Anchor Link

• filing_due_date follows the OSS rule that the return is due by the end of the month following the quarter.
• nil_return_eligible is intentionally conservative: it is only true when zero source events were recorded for the selected quarter.
• If source events exist but none are currently included, the response stays in review_required rather than silently treating the quarter as a nil return.
• The endpoint does not create, lock, or submit a filed return.

Response ShapeCopy Anchor Link

Example RequestCopy Anchor Link

curl "https://api.vat-engine.app/v1/reports/oss-accountant-report?period=2026-Q1" -H "X-API-Key: YOUR_API_KEY"

OSS / IOSS Filing Prep WorkspaceCopy Anchor Link

GET /v1/reports/filing-prep?period=YYYY-Qn

Required scope: full or read-only

Returns an account-scoped filing workspace for the selected quarter. The response combines Union OSS quarter readiness with month-by-month IOSS summaries derived from committed imported_goods supply events.

Business RulesCopy Anchor Link

• Quarter-based reporting endpoints accept supported YYYY-Qn quarter keys only; malformed or out-of-range quarters return 400 invalid_period.
• Union OSS readiness reuses the same preview, warning, nil-return, and payable-balance logic as the existing quarterly summary surface.
• IOSS months are generated from committed imported-goods supply events only.
• IOSS exclusions include missing or overlapping registration coverage, excise goods, consignments above EUR 150, non-EUR consignment values that lack a verified EUR value, missing third-country origin, and rows outside the active registration window.
• Covered months with zero imported-goods source events remain visible as nil_return_candidate because the import scheme return period is monthly.
• The endpoint does not create, lock, submit, or persist a filed return.

Response ShapeCopy Anchor Link

Example RequestCopy Anchor Link

curl "https://api.vat-engine.app/v1/reports/filing-prep?period=2026-Q1" -H "X-API-Key: YOUR_API_KEY"

OSS / IOSS Multi-jurisdiction PreviewCopy Anchor Link

GET /v1/reports/multi-jurisdiction?period=YYYY-Qn

Required scope: full or read-only

Returns a read-only filing-exposure view for the selected quarter. The response reuses the existing Union OSS quarterly preview and country-breakdown rules for reportable Member State totals, then adds month-by-month IOSS summaries for committed imported-goods events inside the quarter.

Business RulesCopy Anchor Link

• Union OSS jurisdiction totals require exactly one overlapping active or ended union_oss registration for the requested quarter.
• Included Union OSS amounts, exclusions, warnings, correction rows, payable balances, and return-currency conversion match the existing quarterly summary and country VAT breakdown endpoints.
• Included rows are grouped by Member State of consumption and preserve the Union OSS sections 2a, 2b, 2c, and 2d.
• IOSS periods are monthly, and each month applies the EUR 150 intrinsic-value ceiling, excise exclusion, registration-window checks, and month-end ECB conversion rules independently.
• The endpoint does not create, lock, submit, or persist a filed return.

Response ShapeCopy Anchor Link

Example RequestCopy Anchor Link

curl "https://api.vat-engine.app/v1/reports/multi-jurisdiction?period=2026-Q1" -H "X-API-Key: YOUR_API_KEY"

Threshold StatusCopy Anchor Link

GET /v1/compliance/threshold-status

Required scope: full or read-only

Returns governed Article 59c threshold evidence for the current and preceding calendar years. VAT Engine selects the reviewed threshold for the supplier's establishment Member State in its statutory currency (for example, PLN 42,000 for Poland), stops current-year evidence at the exact authenticated source-event cutoff, and never substitutes daily reporting FX for the legal threshold. Each candidate has separate disposition, evidence-quality, and materiality dimensions. A B2B, domestic, imported distance-sale, installed-goods, or new-means exclusion therefore remains conclusive when an unrelated field is absent; only a material unresolved fact can block the comparison. An incomplete response contains no checks entry and therefore no exceeded, remaining, percentage, or crossing conclusion. IOSS remains a separate per-consignment test.

Reviewed threshold releases are complete EU27 snapshots. VAT Engine rejects a partial country-only successor before it becomes selectable, so a legal update for one Member State cannot silently remove the still-valid reviewed threshold for another Member State.

The threshold comparison is not a complete place-of-supply decision. Sole-establishment evidence and any Article 59c taxation option are reported as separate applicability conditions. Registration and filing readiness also remain separate from the legal threshold comparison. For goods, destination-versus-establishment is the applicable condition through 31 December 2026. From 1 January 2027, dispatch must also begin in the supplier's establishment Member State. A statutory option and an amount crossing are retained as simultaneous triggers; primary_treatment_driver identifies the deterministic causal trigger for display, while an earlier option never erases factual crossing provenance.

Authenticated refunds linked to an original qualifying supply adjust that supply's statutory calendar-year amount. The first crossing remains immutable historical evidence even if a later adjustment reduces the final net amount. An unlinked correction is material unresolved evidence and blocks publication instead of being silently ignored.

When the dashboard reports a material Article 59c gap, Review imported events opens a queue scoped to events whose unresolved facts can change the statutory result, even if their product classification is already complete. Open source profiles opens the store-level defaults for supplier establishment and normal dispatch. A profile default is used only when the imported event does not provide that fact; authenticated event evidence takes priority. Saving a changed default creates a successor shadow decision without rewriting historical decisions, ledger totals, filing periods, or locked records.

Opening the general Review queue shows only imported events whose effective state currently requires review, and its badge counts that same set. Classified events with material Article 59c fact gaps remain available through the explicit Review imported events action on OSS Overview; they do not inflate the general Review queue badge.

Response FieldsCopy Anchor Link

Example RequestCopy Anchor Link

curl https://api.vat-engine.app/v1/compliance/threshold-status \-H "X-API-Key: YOUR_API_KEY"

Threshold CheckCopy Anchor Link

POST /v1/vat/threshold-check

Required scope: full or read-only

Checks a threshold depending on the type:

• OSS — Evaluates the current and preceding calendar years using the same reviewed establishment-currency policy and authenticated-event aggregation as shadow expected treatment. Arbitrary partial-year ranges are rejected. Incomplete evidence returns 422 article_59c_evidence_incomplete unless an earlier authenticated crossing is already proven; a proven crossing remains available with the incomplete closing-evidence status.
• IOSS — Validates a single consignment amount against the €150 threshold (Art. 369l). No transaction aggregation is performed.

Request Body (OSS)Copy Anchor Link

Request Body (IOSS)Copy Anchor Link

Response FieldsCopy Anchor Link

Example RequestsCopy Anchor Link

# OSS — aggregate checkcurl -X POST https://api.vat-engine.app/v1/vat/threshold-check \-H "X-API-Key: YOUR_API_KEY" \-H "Content-Type: application/json" \-d '{"threshold_type": "oss", "from": "2026-01-01", "to": "2026-03-31"}'# IOSS — per-consignment checkcurl -X POST https://api.vat-engine.app/v1/vat/threshold-check \-H "X-API-Key: YOUR_API_KEY" \-H "Content-Type: application/json" \-d '{"threshold_type": "ioss", "amount_minor": 14500}'