Transactions
Query VAT calculation history, inspect calculation and rate evidence, export versioned CSV files, and aggregate reporting totals.
Overview
Transaction endpoints provide access to your VAT calculation history. All endpoints require a V2 API key with full or read-only scope. Legacy API keys cannot access transaction data.
Transaction history records VAT calculations. OSS threshold monitoring, Filing Prep, and OSS/IOSS
reporting use committed sales data. Calling POST /v1/vat/calculate alone does not add a sale to
those compliance reports.
New authenticated calculations retain typed rate and calculation evidence. Older records remain
legacy_unverifiable rather than being assigned provenance from a matching numeric rate. A new
record is replayable only when its transaction detail reports replay_status: available and the
complete sealed rate, input, result, and calculator evidence is present.
Source Tags
Multi-store and multi-channel reporting uses source_id to identify the commerce system, checkout,
POS, or subscription channel that produced a row. VAT calculation events can populate this value
from the optional X-Source-ID header on POST /v1/vat/calculate; connected-store imports use the
same stable source model for committed order-derived supplies.
Managed source profiles are available through the Sources API. A profile does not rewrite historical source_id values; it gives you an account-owned label and channel definition for the same stable source key.
Recommended source tags are stable store/channel identifiers from 1 to 100 characters using letters, digits, _, -, or /:
shopify-orderswoocommerce/eumagento-deheadless-checkoutpos-berlinstripe-subscriptions
Keep source tags free of personal data and secrets. Do not use customer names, emails, access tokens, or per-order identifiers. Transaction source_id filters are analytical slices for reconciliation and accountant review; compliance totals on OSS/IOSS surfaces still depend on the committed supply data recorded for those sales.
List Transactions
GET /v1/transactionsRequired scope: full or read-only
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
from | string | No | Start date (YYYY-MM-DD). Inclusive. |
to | string | No | End date (YYYY-MM-DD). Inclusive. |
country | string | No | ISO 3166-1 alpha-2 code to filter by destination country. |
currency | string | No | ISO 4217 currency code to filter by currency. |
tax_class_id | string | No | Filter by tax class ID. |
source_id | string | No | Filter by source/store/channel tag captured from X-Source-ID. Use a known source_key from /v1/sources or a raw unresolved tag from /v1/sources/unknown. |
cursor | string | No | Cursor for pagination (from next_cursor in previous response). |
limit | integer | No | Page size from 1 to 500. Defaults to 50. |
api_key_id | integer | No | Filter by dashboard API key ID. |
Example Request
curl "https://api.vat-engine.app/v1/transactions?from=2026-01-01&to=2026-03-31&country=DE" \-H "X-API-Key: YOUR_API_KEY"Every row keeps its existing id and adds rate_evidence_status with one of verified,
legacy_unverifiable, or unavailable.
Get Calculation Evidence
GET /v1/transactions/{id}Required scope: full or read-only
Returns one tenant-owned API calculation audit record. calculation_id is permanently identical
to the transaction id. The response includes the recorded transaction, rate source and version,
effective date, mapping and calculation versions, evidence status, replay status, and ordered
public-safe snapshot references when available.
Malformed identifiers return 400 invalid_transaction_id. A valid UUID owned by another account
returns the same 404 transaction_not_found response as a nonexistent UUID.
curl "https://api.vat-engine.app/v1/transactions/e2d0940e-b123-47b7-80ad-8a3673fa4680" \-H "X-API-Key: YOUR_API_KEY"The transaction detail and ledger describe recorded API calculation evidence, not a committed legal journal. A separate commerce-import shadow decision can never upgrade this evidence status.
Replay An Eligible Calculation
POST /v1/transactions/{id}/replayRequired scope: full or read-only
Recalculates an eligible tenant-owned calculation from its original canonical request, pinned
historical rate evidence, and registered calculator version. Success returns exact_match: true
with the reproduced amounts and the bounded rate and calculation provenance.
curl -X POST "https://api.vat-engine.app/v1/transactions/e2d0940e-b123-47b7-80ad-8a3673fa4680/replay" -H "X-API-Key: YOUR_API_KEY"Unavailable, malformed, nonexistent, and other-account calculation identifiers use the same
404 calculation_not_found response. A sealed-evidence mismatch uses that same unavailable
response; it does not return the canonical input, mismatch reason, or internal evidence and does
not automatically restore replay eligibility.
Exact replay never accepts a caller-selected rate-data or calculator version. Those selections would describe a different, counterfactual calculation rather than a replay of the stored result.
Export Transactions
GET /v1/transactions/exportRequired scope: full or read-only
Returns transaction data as a CSV download. Maximum date range: 367 days. Very large exports are capped at 1,000,000 rows; when the cap is reached, the CSV ends with a trailing comment row indicating truncation.
String cells that begin with spreadsheet formula prefixes such as =, +, -, or @ are prefixed with a leading apostrophe in the export so opening the CSV in Excel, Numbers, or LibreOffice does not execute them as formulas.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
from | string | Yes | Start date (YYYY-MM-DD). Inclusive. |
to | string | Yes | End date (YYYY-MM-DD). Inclusive. |
country | string | No | ISO 3166-1 alpha-2 code to filter by destination country. |
currency | string | No | ISO 4217 currency code to filter by currency. |
tax_class_id | string | No | Filter by tax class ID. |
source_id | string | No | Filter by source/store/channel tag captured from X-Source-ID. Use a known source_key from /v1/sources or a raw unresolved tag from /v1/sources/unknown. |
api_key_id | integer | No | Filter by dashboard API key ID. |
export_version | string | No | 1 (default) preserves the existing CSV columns. 2 adds calculation and rate evidence columns plus ordered snapshot digests. |
Example Request
curl "https://api.vat-engine.app/v1/transactions/export?from=2026-01-01&to=2026-03-31" \-H "X-API-Key: YOUR_API_KEY" \-o transactions.csvIf the result exceeds the export cap, the download still completes and the last CSV row contains a truncation notice.
Use the default export_version=1 for existing import pipelines. Opt in to export_version=2 only
when the consumer accepts the additional provenance columns. Unsupported versions return
400 invalid_export_version.
Aggregated Transactions
GET /v1/transactions/aggregatedRequired scope: full or read-only
Returns aggregated totals for a date range, grouped by the specified dimension. Amounts are reported in EUR cents; non-EUR transactions are converted with ECB reference rates where available.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
from | string | No | Start date (YYYY-MM-DD). Defaults to Jan 1 of current year. |
to | string | No | End date (YYYY-MM-DD). Defaults to today. |
group_by | string | No | Grouping dimension: country (default), tax_class, or month. |
country | string | No | ISO 3166-1 alpha-2 code to filter by destination country. |
source_id | string | No | Filter by source/store/channel tag captured from X-Source-ID. Use a known source_key from /v1/sources or a raw unresolved tag from /v1/sources/unknown. |
currency | string | No | ISO 4217 currency code to filter before EUR normalization. |
api_key_id | integer | No | Filter by dashboard API key ID. |
Response Fields
| Field | Type | Description |
|---|---|---|
group_by | string | The grouping dimension used |
period.from | string | Start date of the aggregation period |
period.to | string | End date of the aggregation period |
rows[].key | string | Group key (country code, tax class ID, or month) |
rows[].transaction_count | integer | Number of transactions in the group |
rows[].gross_amount_minor | integer | Total gross amount in EUR minor units after conversion |
rows[].net_amount_minor | integer | Total net amount in EUR minor units after conversion |
rows[].vat_amount_minor | integer | Total VAT amount in EUR minor units after conversion |
rows[].converted_currencies | string[] | Non-EUR currencies converted in this group |
rows[].unconverted_currencies | string[] | Non-EUR currencies excluded because no ECB rate was found |
converted_currencies | string[] | Non-EUR currencies converted anywhere in the response |
unconverted_currencies | string[] | Non-EUR currencies excluded anywhere in the response |
eur_only | boolean | Backward-compatible flag; true when some rows were excluded |
disclaimer | string | Human-readable conversion note |
Example Request
curl "https://api.vat-engine.app/v1/transactions/aggregated?from=2026-01-01&to=2026-03-31&group_by=country" \-H "X-API-Key: YOUR_API_KEY"Omitting currency includes all currencies and normalizes available non-EUR rows to EUR. Passing
currency=EUR narrows the result to transactions originally recorded in EUR only.