Filings

Overview

The Filings API lets you preview upcoming tax filings, generate them for a jurisdiction, and manage their lifecycle. Filings represent individual tax returns that your business must submit to a tax authority for a specific period. Each filing includes:

Tax period — the date range the filing covers
Reporting period — the date range used for reporting (may differ from the tax period)
Due date — when the return must be filed
Frequency — how often filings occur (monthly, quarterly, annually, etc.)
Status — the current state of the filing (SCHEDULED, UPCOMING, OVERDUE, FILED, etc.)

V2 filings

V2 filings work with V2 registrations and use registration_tax_type_id to identify the jurisdiction and tax type. This replaces the V1 approach of identifying filings by country and state code. V2 filings support:

International jurisdictions — EU member states, UK, Canada, and trade bloc schemes (Union OSS, Non-Union OSS, IOSS)
Composite frequencies — registrations with multiple filing obligations (e.g., quarterly returns plus annual reconciliation)
Content-driven calendars — filing dates and periods are determined by a centralized filing calendar

To use V2 filings, you must first create a V2 registration for the jurisdiction. The registration_tax_type_id from that registration is used to identify filings.

Filing workflow

Preview filings

Use the preview endpoint to see what filings would be generated for a registration and time period. This is a read-only operation — no filings are created.

Generate filings

Use the bulk create endpoint to generate the filings. The system creates filing records based on the filing calendar content for your registration.

Track and manage

Use the list endpoint to view filings and their statuses. Update filings with tax amounts, confirmation numbers, and status changes as you prepare and submit returns.

Delete if needed

Use the bulk delete endpoint to remove filings that are no longer needed. Filed returns cannot be deleted.

Filing response fields

V2 filings include additional fields compared to V1:

Field	Description
`registration_tax_type_id`	The V2 content ID linking the filing to a registration
`jurisdiction_name`	Human-readable jurisdiction name (e.g., “California”, “Germany”)
`jurisdiction_type`	Type of jurisdiction (e.g., `STATE_OR_PROVINCE`, `COUNTRY`, `TRADEBLOC`)
`filing_content_id`	Content identifier linking the filing to its calendar entry and contribution box rules. Used together with `registration_tax_type_id` to distinguish parallel filing tracks under the same registration (e.g., a standard return vs. a Dauerfrist extension in Germany). Present for V2 filings with content-driven calendars; null for V1 filings.
`form_title`	The display name of the filing form
`description`	Additional description for the filing
`reporting_period_start_date`	Start of the reporting period
`reporting_period_end_date`	End of the reporting period

Filing contributions

For EU and UK filings, Commenda automatically computes the values for each box on the tax return form. These computed values are called filing contributions. Contributions are generated during the automated tax breakdown processing cycle for any filing that has content-defined box rules (identified by a filing_content_id). The engine:

Validates that invoices attached to the filing have the required data (such as ship-from addresses)
Aggregates invoice data into buckets grouped by geographic origin/destination, transaction type, tax rate, product type, customer type, and remitter type
Evaluates AGGREGATE box rules by matching content-defined filters against invoice buckets and summing the appropriate monetary field (taxable amount, tax amount, or gross amount)
Evaluates FORMULA box rules in sequence, referencing previously computed box values with simple arithmetic

Supported filing types

Type	Description
Country-level	Standard VAT returns for a single jurisdiction (e.g., Germany, France, Italy)
Union OSS	One-stop shop returns with per-member-state breakdowns for intra-EU B2C sales
Non-Union OSS	One-stop shop returns for non-EU businesses selling B2C services in the EU
IOSS	Import one-stop shop returns for low-value goods imported into the EU

Country-level filing contributions are supported for 23 EU member states: Austria, Belgium, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Finland, France, Germany, Greece, Hungary, Italy, Latvia, Lithuania, Luxembourg, Malta, Poland, Portugal, Romania, Slovakia, Slovenia, and Spain. Each country includes box rules covering domestic sales at all applicable rate tiers (standard, reduced, super-reduced, and extra-reduced where applicable), domestic purchases, intra-community sales and acquisitions, zero-rated domestic sales, imports, exports, and a formula-based total output VAT box. Sales and returns are automatically netted within each box. For country-level filings, box values are computed once using the filing jurisdiction’s rates. For trade-bloc filings (OSS/IOSS), the engine iterates over each destination member state, resolving that state’s rates and producing per-jurisdiction contributions.

Retrieving contributions

Use the GET /filings/{id}/contributions endpoint to retrieve computed contributions for a single filing, or the POST /filings/contributions batched endpoint to fetch contributions for up to 100 filings in one request. Each contribution includes:

Field	Description
`filing_contribution_id`	Content-defined identifier linking the value to its box rule definition
`box_id`	The tax return box identifier (e.g., `"81"` for German domestic supplies)
`box_name`	Display name of the box
`box_order`	Display order on the form
`box_type`	Classification (e.g., `TAX_BASE`, `TAX_AMOUNT`)
`value`	Computed amount in minor currency units (e.g., cents)
`filing_through_jurisdiction`	For OSS/IOSS filings, the Commenda jurisdiction ID of the destination member state. Null for country-level filings

// Example: GET /filings/{id}/contributions
{
  "data": {
    "count": 3,
    "contributions": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "filing_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "filing_contribution_id": "DE_VAT_01",
        "filing_through_jurisdiction": null,
        "value": 150000,
        "value_type": "INTEGER",
        "box_id": "81",
        "box_name": "Supplies and other services",
        "box_order": 1,
        "box_type": "TAX_BASE"
      }
    ]
  },
  "message": "Successfully fetched filing contributions."
}

Invoice validation

During contribution processing, Commenda validates that each invoice has the data required for accurate box computation. Invoices that fail validation are stamped with a per-invoice error code on tax_breakdown_processing_error_code and excluded from contribution calculations until the underlying issue is resolved and the next processing cycle runs.

Error code	Meaning
`TRANSACTION.ADDRESSES.SHIP_FROM.MISSING`	The invoice has no ship-from address. EU VAT contribution computation needs ship-from to determine intra-EU vs. extra-EU scope.
`TRANSACTION.CURRENCY.FX_RATE_UNAVAILABLE`	The invoice’s `(invoice_currency, transacted_at)` pair cannot be converted to the filing’s reporting currency because no FX rate is published for that exact date.

Contributions are idempotent — each processing run replaces all previous contribution values for the filing. This means contributions always reflect the current state of your transaction data.

Reporting currency and FX conversion

EU and UK V2 filings declare a reporting_currency on their content filing calendar entry (for example, EUR for German country-level returns, GBP for UK returns). When invoices attached to a filing span multiple currencies, the contribution engine converts each invoice’s taxable, tax, and gross amounts from invoice_currency into the filing’s reporting currency at aggregation time. Conversion uses the invoice’s transacted_at date to look up the cross-rate. Same-currency invoices short-circuit to a rate of 1.0 — single-currency filings produce values byte-identical to filings computed before FX support was introduced.

Exact-date matching

The engine requires an FX rate published for the exact transacted_at date. There is no fallback to the nearest prior date. Filings are authoritative documents, so any gap in the FX rate table for a date that an invoice transacted on must be backfilled before that invoice can be included in a return. When any invoice on a filing cannot be converted, contribution processing fails the entire job:

The filing’s contribution sync job is marked FAILED with reason FX_RATE_UNAVAILABLE: N invoice(s) could not be converted to <CURRENCY>.
The job’s failure_count reflects the number of flagged invoices and success_count reflects the unaffected remainder.
Each flagged invoice is stamped with TRANSACTION.CURRENCY.FX_RATE_UNAVAILABLE on tax_breakdown_processing_error_code so the UI can highlight which transactions need attention.
No contribution rows are written. Any previously-correct contributions on the filing are left intact until the FX gap is filled and the sync re-runs.

This fail-loud behavior prevents silently submitting a VAT return that omits legitimate revenue. To recover, backfill the missing FX rate and re-trigger contribution sync — the engine clears the per-invoice error codes and re-validates on each run.

A filing without a reporting_currency populated on its content filing calendar entry fails contribution sync with MISSING_FILING_CURRENCY. This is a content configuration gap and must be fixed at the calendar level.

US and Canadian filings

US and Canadian filings are not affected by this conversion path. They use a separate calculation engine that bakes FX into invoice amounts at calc time, targeting USD or CAD respectively.

Liability report

The liability report endpoints provide per-filing snapshots and bulk exports across multiple filings. The two read endpoints return distinct shapes — call them in parallel and merge by filing_id when you need both filing-level totals and box-level VAT detail.

Endpoint	Description
`POST /filings/liability-report`	Returns per-filing liability snapshots. Each entry’s `breakdown` object is populated for US and Canadian filings, and `null` for VAT filings.
`POST /filings/contributions`	Returns per-filing tax-return box contributions for up to 100 filings. `contributions` is non-null for VAT filings and `null` for US and Canadian filings.
`POST /filings/liability-report/export`	Queues an asynchronous job that produces one CSV per filing, bundles them into a zip, and emails a signed download link to the recipients you specify.

All three endpoints accept up to 100 filing IDs per request. The export endpoint also requires every filing in the request to belong to the same corporation. Track the export job with the jobs endpoint, filtering by entity=FILING and operation=EXPORT_INDIRECT_TAX_FILINGS_LIABILITY_REPORT. For multi-filing exports, the worker creates one child job row per filing (with entity_id set to the filing UUID) so the per-filing detail page surfaces the export.

Managed filing

When you enable managed_filing_enabled on a V2 registration, Commenda handles the filing process for that jurisdiction on your behalf. You can toggle this setting when creating or updating a registration.

API endpoints

Endpoint	Method	Description
`/internal/filings/preview`	POST	Preview proposed filings for a registration
`/internal/filings/bulk/create`	POST	Generate filings for a registration
`/internal/filings/bulk/delete`	DELETE	Delete filings by registration or filing IDs
`/filings/{id}`	GET	Get a single filing
`/filings/{id}/contributions`	GET	List filing contributions
`/filings/contributions`	POST	Get filing contributions for up to 100 filings
`/filings/liability-report`	POST	Get per-filing liability snapshots
`/filings/liability-report/export`	POST	Queue an async zipped-CSV export of liability reports

Get Started

Registrations

Registrations V2

Corporations

Tax Calculations

Transactions

Address Requirements

Registration Thresholds

Products

Customers

Exemption Certificates

Exemptions

Files

Credentials

Locations

Webhooks

Filings

Overview

V2 filings

Filing workflow

Filing response fields

Filing contributions

Supported filing types

Retrieving contributions

Invoice validation

Reporting currency and FX conversion

Exact-date matching

US and Canadian filings

Liability report

Managed filing

API endpoints

​Overview

​V2 filings

​Filing workflow

​Filing response fields

​Filing contributions

​Supported filing types

​Retrieving contributions

​Invoice validation

​Reporting currency and FX conversion

​Exact-date matching

​US and Canadian filings

​Liability report

​Managed filing

​API endpoints

Overview

V2 filings

Filing workflow

Filing response fields

Filing contributions

Supported filing types

Retrieving contributions

Invoice validation

Reporting currency and FX conversion

Exact-date matching

US and Canadian filings

Liability report

Managed filing

API endpoints