Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.commenda.io/llms.txt

Use this file to discover all available pages before exploring further.

​
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

1

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

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

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

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:
FieldDescription
registration_tax_type_idThe V2 content ID linking the filing to a registration
jurisdiction_nameHuman-readable jurisdiction name (e.g., “California”, “Germany”)
jurisdiction_typeType of jurisdiction (e.g., STATE_OR_PROVINCE, COUNTRY, TRADEBLOC)
filing_content_idContent 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_titleThe display name of the filing form
descriptionAdditional description for the filing
reporting_period_start_dateStart of the reporting period
reporting_period_end_dateEnd 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:
  1. Validates that invoices attached to the filing have the required data (such as ship-from addresses)
  2. Aggregates invoice data into buckets grouped by geographic origin/destination, transaction type, tax rate, product type, customer type, and remitter type
  3. 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)
  4. Evaluates FORMULA box rules in sequence, referencing previously computed box values with simple arithmetic

​
Supported filing types

TypeDescription
Country-levelStandard VAT returns for a single jurisdiction (e.g., Germany, France, Italy)
Union OSSOne-stop shop returns with per-member-state breakdowns for intra-EU B2C sales
Non-Union OSSOne-stop shop returns for non-EU businesses selling B2C services in the EU
IOSSImport 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:
FieldDescription
filing_contribution_idContent-defined identifier linking the value to its box rule definition
box_idThe tax return box identifier (e.g., "81" for German domestic supplies)
box_nameDisplay name of the box
box_orderDisplay order on the form
box_typeClassification (e.g., TAX_BASE, TAX_AMOUNT)
valueComputed amount in minor currency units (e.g., cents)
filing_through_jurisdictionFor 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 codeMeaning
TRANSACTION.ADDRESSES.SHIP_FROM.MISSINGThe 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_UNAVAILABLEThe 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.
EndpointDescription
POST /filings/liability-reportReturns per-filing liability snapshots. Each entry’s breakdown object is populated for US and Canadian filings, and null for VAT filings.
POST /filings/contributionsReturns 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/exportQueues 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

EndpointMethodDescription
/internal/filings/previewPOSTPreview proposed filings for a registration
/internal/filings/bulk/createPOSTGenerate filings for a registration
/internal/filings/bulk/deleteDELETEDelete filings by registration or filing IDs
/filings/{id}GETGet a single filing
/filings/{id}/contributionsGETList filing contributions
/filings/contributionsPOSTGet filing contributions for up to 100 filings
/filings/liability-reportPOSTGet per-filing liability snapshots
/filings/liability-report/exportPOSTQueue an async zipped-CSV export of liability reports