Compliance

Overview

Compliance endpoints help you monitor EU One-Stop Shop (OSS) distance selling thresholds, 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 status with tax-registration data to produce a conflict-aware, registration-aware OSS Overview and threshold alerts. Read endpoints require a V2 API key with full or read-only scope; write endpoints require full scope.

OSS / IOSS Tax Registrations

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. The backend rejects overlapping non-excluded effective windows for the same scheme.

Registration Fields

Reporting Eligibility

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 Request

curl -X POST https://api.vat-engine.daily-automations.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 Preview

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 Rules

• 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 Fields

Warning Codes

Example Request

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

Union OSS Country VAT Breakdown Preview

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 Fields

Example Request

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

Union OSS Accountant Exports

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 Behavior

• 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 Fields

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 Field

Export rows use vat_rate_pct, for example 20.00 or 7.00, instead of the internal vat_rate_bps representation. This matches the existing transaction CSV export convention and is intended for accountant-readable files.

Manifest Fields

Example Requests

# Quarterly summary JSON packagecurl -L "https://api.vat-engine.daily-automations.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.daily-automations.app/v1/reports/country-vat-breakdown/export?period=2026-Q1&format=csv" -H "X-API-Key: YOUR_API_KEY"

Locked Union OSS Return Periods

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.

Behavior

• 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 Fields

Example Requests

# List recent locked quarterscurl "https://api.vat-engine.daily-automations.app/v1/reports/locked-return-periods/union-oss" -H "X-API-Key: YOUR_API_KEY"# Lock a quartercurl -X POST "https://api.vat-engine.daily-automations.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.daily-automations.app/v1/reports/locked-return-periods/union-oss/filed?period=2026-Q1" -H "X-API-Key: YOUR_API_KEY"

Union OSS Accountant Format

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 Rules

• 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 Shape

Example Request

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

OSS / IOSS Filing Prep Workspace

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 Rules

• 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 Shape

Example Request

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

OSS / IOSS Multi-jurisdiction Preview

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 Rules

• 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 Shape

Example Request

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

Threshold Status

GET /v1/compliance/threshold-status

Required scope: full or read-only

Returns the current OSS threshold status for your account based on year-to-date committed, threshold-eligible B2C supply events. Non-EUR amounts are converted to EUR using ECB reference rates where available. Imported goods, non-TBE services, non-sale events, rows awaiting classification, and supplies without the required cross-border evidence are excluded from this threshold slice. IOSS is per-consignment (Art. 369l) and not included in annual cumulative totals — use the Threshold Check endpoint for IOSS validation.

Response Fields

Example Request

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

Threshold Check

POST /v1/vat/threshold-check

Required scope: full or read-only

Checks a threshold depending on the type:

• OSS — Aggregates committed, threshold-eligible B2C supply events over a date range and converts non-EUR rows to EUR using ECB reference rates where available before comparing against the €10 000 annual threshold (Art. 59c). Imported goods, non-TBE services, non-sale events, rows awaiting classification, and supplies without the required cross-border evidence are excluded from this threshold slice.
• IOSS — Validates a single consignment amount against the €150 threshold (Art. 369l). No transaction aggregation is performed.

Request Body (OSS)

Request Body (IOSS)

Response Fields

Example Requests

# OSS — aggregate checkcurl -X POST https://api.vat-engine.daily-automations.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.daily-automations.app/v1/vat/threshold-check \-H "X-API-Key: YOUR_API_KEY" \-H "Content-Type: application/json" \-d '{"threshold_type": "ioss", "amount_minor": 14500}'