Transactions

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.

Transactions are the audit ledger for VAT calculations (vat_transactions). OSS threshold monitoring, Filing Prep, and OSS/IOSS reporting use committed supply events from a separate compliance ledger. A POST /v1/vat/calculate row does not move those compliance surfaces unless the same sale is also committed into the supply ledger.

Source Tags

Multi-store and multi-channel reporting uses source_id to identify the commerce system, CMS, checkout, POS, or subscription channel that produced a transaction row. VAT calculation events can populate this value from the optional X-Source-ID header on POST /v1/vat/calculate; future order-sync/import flows can use the same stable source tags for CMS-originated transactions.

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-orders
woocommerce/eu
magento-de
headless-checkout
pos-berlin
stripe-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/transactions

Required 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.daily-automations.app/v1/transactions?from=2026-01-01&to=2026-03-31&country=DE" \-H "X-API-Key: YOUR_API_KEY"

Export Transactions

GET /v1/transactions/export

Required 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.

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.

Example Request

curl "https://api.vat-engine.daily-automations.app/v1/transactions/export?from=2026-01-01&to=2026-03-31" \-H "X-API-Key: YOUR_API_KEY" \-o transactions.csv

Export runs with backend safety guardrails for large datasets. If the result exceeds the export cap, the download still completes and the last CSV row is a comment-style truncation note.

Aggregated Transactions

GET /v1/transactions/aggregated

Required 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.daily-automations.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.

On this page