# Filing periods tools > MCP tools for Filing periods: filing_periods_calendar, filing_periods_documents_upload, filing_periods_get, filing_periods_list, filing_periods_lock, filing_periods_mark_paid, filing_periods_package, filing_periods_prepare, filing_periods_report, filing_periods_schedules, filing_periods_set_schedule, filing_periods_submit. - `filing_periods_calendar`: Filing calendar - `filing_periods_documents_upload`: Upload a filing document - `filing_periods_get`: Get a filing period - `filing_periods_list`: List filing periods - `filing_periods_lock`: Lock a filing period - `filing_periods_mark_paid`: Mark a return paid - `filing_periods_package`: Get a filing package - `filing_periods_prepare`: Prepare a filing period's report - `filing_periods_report`: Download a filing report - `filing_periods_schedules`: List filing schedules - `filing_periods_set_schedule`: Set a registration's filing schedule - `filing_periods_submit`: Mark a return submitted ## `filing_periods_calendar` **Filing calendar.** Operation [`filing_periods.calendar`](https://ownrecord.io/docs/reference/filing-periods-calendar.md) · Organization level · permission `filings:read` · risk tier `read` · since M8 The filing calendar (spec §21.3): filing periods of every legal entity of the organization, or of one entity (an entity key, or `entity_id`), in the mode of the request, earliest due date first. By default only the periods not paid yet (`open`, `locked`, `prepared`, `submitted`); filter by `status`, by due date with `dueFrom` and `dueTo`, and cap with `limit` (default 100). Each item is the period with its entity's name and slug, the whole days until it is due (`daysUntilDue`, negative once past) and `overdue` (past the due instant and not yet submitted). Ownrecord also reminds the entity's tax managers and finance team 14, 7 and 2 days before each due date (alerts `FILING_DUE_14`, `FILING_DUE_7`, `FILING_DUE_2`). Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------- | | `status` | one of `open`, `locked`, `prepared`, `submitted`, `paid` or array of one of `open`, `locked`, `prepared`, `submitted`, `paid` | no | Only periods in these statuses. Default: every period not paid yet. | | `dueFrom` | string | no | Due on or after this date (UTC), `YYYY-MM-DD`. | | `dueTo` | string | no | Due on or before this date (UTC), `YYYY-MM-DD`. | | `limit` | integer | no | At most this many periods, 1 to 500 (default 100). (1–500) | | `entity_id` | ID (`ent_…`) | no | Optional: act inside this legal entity (ent\_…) instead of the whole organization. | | `brand_id` | ID (`brd_…`) | no | Optional: act inside this brand (brd\_…) instead of the whole organization. | - **Scope:** the whole organization, or one legal entity or brand of it with `entity_id` or `brand_id`. - **Read-only:** changes nothing; `idempotency_key` is ignored. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A filter is malformed (`param` names it). - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see filings here. ### Example **What is due next across the organization** Arguments: ```json {} ``` Result `output`: ```json { "object": "list", "data": [ { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "object": "filing_period", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "reportKind": "eu_oss", "reportAvailable": true, "frequency": "quarterly", "periodKey": "2026-Q3", "periodStart": "2026-06-30T22:00:00.000Z", "periodEnd": "2026-09-30T22:00:00.000Z", "firstDay": "2026-07-01", "lastDay": "2026-09-30", "timeZone": "Europe/Zagreb", "currency": "EUR", "dueDate": "2026-10-31", "dueAt": "2026-10-31T22:59:59.000Z", "lockableAt": "2026-09-30T22:00:00.000Z", "status": "open", "statusChangedAt": "2026-07-01T03:00:00.000Z", "lockedAt": null, "preparedAt": null, "submittedAt": null, "reference": null, "paidAt": null, "paymentRef": null, "totals": null, "createdAt": "2026-07-01T03:00:00.000Z", "updatedAt": "2026-07-01T03:00:00.000Z", "entityName": "Acme Digital d.o.o.", "entitySlug": "acme-hr", "daysUntilDue": 11, "overdue": false }, { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y1", "object": "filing_period", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "HR_DOMESTIC", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "reportKind": "eu_domestic", "reportAvailable": true, "frequency": "monthly", "periodKey": "2026-10", "periodStart": "2026-09-30T22:00:00.000Z", "periodEnd": "2026-10-31T23:00:00.000Z", "firstDay": "2026-10-01", "lastDay": "2026-10-31", "timeZone": "Europe/Zagreb", "currency": "EUR", "dueDate": "2026-11-20", "dueAt": "2026-11-20T22:59:59.000Z", "lockableAt": "2026-10-31T23:00:00.000Z", "status": "open", "statusChangedAt": "2026-07-01T03:00:00.000Z", "lockedAt": null, "preparedAt": null, "submittedAt": null, "reference": null, "paidAt": null, "paymentRef": null, "totals": null, "createdAt": "2026-07-01T03:00:00.000Z", "updatedAt": "2026-07-01T03:00:00.000Z", "entityName": "Acme Digital d.o.o.", "entitySlug": "acme-hr", "daysUntilDue": 31, "overdue": false } ] } ``` ## `filing_periods_documents_upload` **Upload a filing document.** Operation [`filing_periods.documents.upload`](https://ownrecord.io/docs/reference/filing-periods-documents-upload.md) · Legal entity level · permission `filings:write` · risk tier `write` · since M8 Uploads a document to a filing period, typically the tax portal's confirmation of the filed return. Send the file base64-encoded in `content`: a PDF, PNG, JPEG or WebP file of at most 3 MB, with its `filename`. The type is read from the file itself. The document is stored privately (spec §7.10) and returned with its `file_…` ID: pass it as a receipt to `filing_periods.submit`. Uploading the same file again returns the same document. Write tier: tax managers, finance, owners and admins. Dry-run it to check a file without storing it. Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------------- | ----------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | ID (`fp_…`) | yes | The filing period (`fp_…`). | | `content` | string | yes | The file's bytes, base64-encoded: a PDF, PNG, JPEG or WebP file of at most 3 MB. (1–4294304 characters) | | `filename` | string | no | The file's name. (1–200 characters) | | `contentType` | one of `application/pdf`, `image/png`, `image/jpeg`, `image/webp` | no | The file's type. Optional: it is read from the file, and must agree when given. | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | | `idempotency_key` | string | no | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) | | `dry_run` | boolean | no | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`) | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours). - **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is malformed (`param` names it). - [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No filing period with this ID exists for this legal entity and mode. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity (an org key without `Ownrecord-Entity`). - [`upstream_timeout`](https://ownrecord.io/docs/reference/errors.md#upstream_timeout): The file store didn't answer in time; nothing was recorded. Retry. - [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The period changed at the same moment. Reload it and try again. - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't work on this entity's filings (tax managers, finance, owners and admins can). ### Example **Upload the OSS portal's confirmation** Arguments: ```json { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "content": "JVBERi0xLjQKJcOkw7zDtsOfCjEgMCBvYmoKPDwvVHlwZS9DYXRhbG9nPj4KZW5kb2JqCnRyYWlsZXIKPDwvUm9vdCAxIDAgUj4+CiUlRU9GCg==", "filename": "oss-q3-confirmation.pdf", "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy", "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21" } ``` Result `output`: ```json { "id": "file_01m4tx5nj8emwbyf7y9vcf47y4", "object": "filing_document", "filingPeriodId": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "filename": "oss-q3-confirmation.pdf", "contentType": "application/pdf", "size": 48213, "sha256": "3e7a1c9f5b2d8e4a6c0f3b7d1e9a5c2f8b4d6e0a3c7f1b9d5e2a8c4f6b0d3e7a", "createdAt": "2026-10-15T09:00:00.000Z" } ``` ## `filing_periods_get` **Get a filing period.** Operation [`filing_periods.get`](https://ownrecord.io/docs/reference/filing-periods-get.md) · Legal entity level · permission `filings:read` · risk tier `read` · since M8 Returns one filing period: its dates, due date and status, the registration it files for, and once prepared the report (spec §21.2): its totals in the filing currency, its sections (for the EU One-Stop Shop: supplies per member state and rate, corrections of earlier periods, the balance per member state), the ECB rates it converted with, and the reconciliation with the ledger's tax payable per jurisdiction and currency. Money cells are micros and rates parts per million, as strings. `files` are the report's CSV and XLSX (`filing_periods.report`), `receipts` the submission's confirmation, `paymentLedgerTxnIds` the ledger postings of the payment. `actions` says which of lock, prepare, submit and mark paid the period allows now, and if not, why (the error code it would fail with). Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | ID (`fp_…`) | yes | The filing period (`fp_…`). | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Read-only:** changes nothing; `idempotency_key` is ignored. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is malformed (`param` names it). - [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No filing period with this ID exists for this legal entity and mode. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity (an org key without `Ownrecord-Entity`). - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see this entity's filings. ### Example **A prepared OSS return** Arguments: ```json { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy" } ``` Result `output`: ```json { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "object": "filing_period", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "reportKind": "eu_oss", "reportAvailable": true, "frequency": "quarterly", "periodKey": "2026-Q3", "periodStart": "2026-06-30T22:00:00.000Z", "periodEnd": "2026-09-30T22:00:00.000Z", "firstDay": "2026-07-01", "lastDay": "2026-09-30", "timeZone": "Europe/Zagreb", "currency": "EUR", "dueDate": "2026-10-31", "dueAt": "2026-10-31T22:59:59.000Z", "lockableAt": "2026-09-30T22:00:00.000Z", "status": "prepared", "statusChangedAt": "2026-10-02T08:05:00.000Z", "lockedAt": "2026-10-02T08:00:00.000Z", "preparedAt": "2026-10-02T08:05:00.000Z", "submittedAt": null, "reference": null, "paidAt": null, "paymentRef": null, "totals": { "currency": "EUR", "taxable": "1500000000", "tax": "290000000", "corrections": "-19000000", "due": "271000000", "refundable": "0" }, "createdAt": "2026-07-01T03:00:00.000Z", "updatedAt": "2026-10-02T08:05:00.000Z", "registration": { "id": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "state": "registered", "registrationNumber": "HR12345678901", "effectiveFrom": "2026-03-31T22:00:00.000Z" }, "endsBeforeRegistration": false, "report": { "kind": "eu_oss", "currency": "EUR", "rounding": "half_up", "fxRule": null, "generatedAt": "2026-10-02T08:05:00.000Z", "fx": [], "sections": [ { "id": "supplies", "title": "Supplies by member state of consumption and rate", "columns": [ { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "rate", "label": "VAT rate", "type": "rate" }, { "key": "rateKind", "label": "Rate type", "type": "text" }, { "key": "taxable", "label": "Taxable amount", "type": "money" }, { "key": "vat", "label": "VAT", "type": "money" }, { "key": "lines", "label": "Lines", "type": "count" } ], "rows": [ { "memberState": "DE", "rate": "190000", "rateKind": "standard", "taxable": "1000000000", "vat": "190000000", "lines": 8 }, { "memberState": "FR", "rate": "200000", "rateKind": "standard", "taxable": "500000000", "vat": "100000000", "lines": 3 } ] }, { "id": "corrections", "title": "Corrections of earlier periods", "columns": [ { "key": "originalPeriod", "label": "Period corrected", "type": "text" }, { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "taxable", "label": "Taxable amount", "type": "money" }, { "key": "vat", "label": "VAT", "type": "money" }, { "key": "lines", "label": "Lines", "type": "count" } ], "rows": [ { "originalPeriod": "2026-Q2", "memberState": "DE", "taxable": "-100000000", "vat": "-19000000", "lines": 1 } ] }, { "id": "balances", "title": "VAT due per member state", "columns": [ { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "supplies", "label": "VAT on supplies", "type": "money" }, { "key": "corrections", "label": "Corrections", "type": "money" }, { "key": "balance", "label": "Balance", "type": "money" } ], "rows": [ { "memberState": "DE", "supplies": "190000000", "corrections": "-19000000", "balance": "171000000" }, { "memberState": "FR", "supplies": "100000000", "corrections": "0", "balance": "100000000" } ] }, { "id": "reconciliation", "title": "Reconciliation with the ledger", "columns": [ { "key": "jurisdiction", "label": "Jurisdiction", "type": "text" }, { "key": "currency", "label": "Currency", "type": "text" }, { "key": "reportTax", "label": "Report tax", "type": "money" }, { "key": "ledgerTax", "label": "Ledger tax payable", "type": "money" }, { "key": "difference", "label": "Difference", "type": "money" } ], "rows": [ { "jurisdiction": "DE", "currency": "EUR", "reportTax": "171000000", "ledgerTax": "171000000", "difference": "0" }, { "jurisdiction": "FR", "currency": "EUR", "reportTax": "100000000", "ledgerTax": "100000000", "difference": "0" } ] } ], "reconciliation": { "matches": true, "rows": [ { "jurisdictionId": "DE", "currency": "EUR", "reportTax": "171000000", "ledgerTax": "171000000", "difference": "0" }, { "jurisdictionId": "FR", "currency": "EUR", "reportTax": "100000000", "ledgerTax": "100000000", "difference": "0" } ] }, "counts": { "lines": 12, "corrections": 1, "notReported": 0, "documents": 12 } }, "files": [ { "format": "csv", "fileId": "file_01m4tx5nj8emwbyf7y9vcf47y2", "filename": "EU_OSS_UNION-2026-Q3.csv", "contentType": "text/csv; charset=utf-8", "size": 2381, "sha256": "5d1c9d6b7f3e0a4c8b2f1e6d9a7c3b5e0f4d8a2c6b1e9f7d3a5c0b8e2f6d4a1c" }, { "format": "xlsx", "fileId": "file_01m4tx5nj8emwbyf7y9vcf47y3", "filename": "EU_OSS_UNION-2026-Q3.xlsx", "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "size": 9184, "sha256": "8a3f6c1e9d4b7a2f5c0e8d3b6a1f4c9e7d2b5a0f3c8e6d1b4a9f7c2e5d0b3a6f" } ], "receipts": [], "paymentLedgerTxnIds": [], "reminders": [], "history": [ { "from": null, "to": "open", "at": "2026-07-01T03:00:00.000Z", "by": "system", "note": null }, { "from": "open", "to": "locked", "at": "2026-10-02T08:00:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null }, { "from": "locked", "to": "prepared", "at": "2026-10-02T08:05:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null } ], "actions": { "lock": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is prepared: \"lock\" needs open." }, "prepare": { "allowed": true, "code": null, "message": null }, "submit": { "allowed": true, "code": null, "message": null }, "markPaid": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is prepared: \"mark_paid\" needs submitted." } } } ``` ## `filing_periods_list` **List filing periods.** Operation [`filing_periods.list`](https://ownrecord.io/docs/reference/filing-periods-list.md) · Legal entity level · permission `filings:read` · risk tier `read` · since M8 Lists the legal entity's filing periods in the mode of the request, newest first. Ownrecord creates a period for every regime the entity is registered in (or in a grace period for), from the regime's filing rules: its frequency and due date (spec §21.1). A period covers every brand of the entity. Filter by `regimeId` (`EU_OSS_UNION` for the Union OSS return) or `status` to find the period to prepare, lock or package: those operations take its ID. Each period has its `periodKey` (`2026-Q3`, `2026-07` or `2026`), its first and last day in the entity's time zone, the `dueDate` and `dueAt` (23:59:59 local time), its `status` (`open`, `locked`, `prepared`, `submitted`, `paid`) and, once prepared, the report's `totals` in the filing currency. Paginate with `limit` (1–100, default 10) and `starting_after`. Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `regimeId` | string | no | Only this regime's periods, e.g. `EU_OSS_UNION`. (1–100 characters) | | `status` | one of `open`, `locked`, `prepared`, `submitted`, `paid` or array of one of `open`, `locked`, `prepared`, `submitted`, `paid` | no | Only periods in this status (or these statuses). | | `limit` | integer | no | Page size, 1 to 100 (default 10). (1–100) | | `starting_after` | ID (`fp_…`) | no | The `next_cursor` of the previous page. | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Read-only:** changes nothing; `idempotency_key` is ignored. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A filter or the page size is malformed (`details.issues`). - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity (an org key without `Ownrecord-Entity`). - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see this entity's filings (brand-scoped members never can). ### Example **The OSS returns still to file** Arguments: ```json { "regimeId": "EU_OSS_UNION", "status": ["open", "locked", "prepared"], "limit": 10, "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy" } ``` Result `output`: ```json { "object": "list", "data": [ { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y1", "object": "filing_period", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "reportKind": "eu_oss", "reportAvailable": true, "frequency": "quarterly", "periodKey": "2026-Q4", "periodStart": "2026-09-30T22:00:00.000Z", "periodEnd": "2026-12-31T23:00:00.000Z", "firstDay": "2026-10-01", "lastDay": "2026-12-31", "timeZone": "Europe/Zagreb", "currency": "EUR", "dueDate": "2027-01-31", "dueAt": "2027-01-31T22:59:59.000Z", "lockableAt": "2026-12-31T23:00:00.000Z", "status": "open", "statusChangedAt": "2026-10-01T03:00:00.000Z", "lockedAt": null, "preparedAt": null, "submittedAt": null, "reference": null, "paidAt": null, "paymentRef": null, "totals": null, "createdAt": "2026-10-01T03:00:00.000Z", "updatedAt": "2026-10-01T03:00:00.000Z" }, { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "object": "filing_period", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "reportKind": "eu_oss", "reportAvailable": true, "frequency": "quarterly", "periodKey": "2026-Q3", "periodStart": "2026-06-30T22:00:00.000Z", "periodEnd": "2026-09-30T22:00:00.000Z", "firstDay": "2026-07-01", "lastDay": "2026-09-30", "timeZone": "Europe/Zagreb", "currency": "EUR", "dueDate": "2026-10-31", "dueAt": "2026-10-31T22:59:59.000Z", "lockableAt": "2026-09-30T22:00:00.000Z", "status": "prepared", "statusChangedAt": "2026-10-02T08:05:00.000Z", "lockedAt": "2026-10-02T08:00:00.000Z", "preparedAt": "2026-10-02T08:05:00.000Z", "submittedAt": null, "reference": null, "paidAt": null, "paymentRef": null, "totals": { "currency": "EUR", "taxable": "1500000000", "tax": "290000000", "corrections": "-19000000", "due": "271000000", "refundable": "0" }, "createdAt": "2026-07-01T03:00:00.000Z", "updatedAt": "2026-10-02T08:05:00.000Z" } ], "has_more": false, "next_cursor": null } ``` ## `filing_periods_lock` **Lock a filing period.** Operation [`filing_periods.lock`](https://ownrecord.io/docs/reference/filing-periods-lock.md) · Legal entity level · permission `filings:write` · risk tier `compliance` · since M8 Locks a filing period that is over (spec §21.1): the first step of a return. The period's documents are complete, so its report can be generated (`filing_periods.prepare`). A refund or credit note issued later is dated when it is issued and goes into a later return as a correction of this period (spec §9.6). Works on an `open` period from its `lockableAt` on (its end). Compliance tier (spec §41.4): tax managers, finance, owners and admins; an agent's call needs approval under the default policy. Returns the period. Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: false` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | ID (`fp_…`) | yes | The filing period (`fp_…`). | | `note` | string | no | A note for the period's history, e.g. who checked the figures. (1–1000 characters) | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | | `idempotency_key` | string | no | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) | | `dry_run` | boolean | no | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`) | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours). - **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is malformed (`param` names it). - [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No filing period with this ID exists for this legal entity and mode. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity (an org key without `Ownrecord-Entity`). - [`filing_period_status_invalid`](https://ownrecord.io/docs/reference/errors.md#filing_period_status_invalid): The period isn't `open` (`details.status`). - [`filing_period_not_ended`](https://ownrecord.io/docs/reference/errors.md#filing_period_not_ended): The period isn't over yet (`details.lockable_at`). - [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The period changed at the same moment. Reload it and try again. - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't work on this entity's filings (tax managers, finance, owners and admins can). ### Example **Lock the Q3 OSS period** Arguments: ```json { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy", "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21" } ``` Result `output`: ```json { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "object": "filing_period", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "reportKind": "eu_oss", "reportAvailable": true, "frequency": "quarterly", "periodKey": "2026-Q3", "periodStart": "2026-06-30T22:00:00.000Z", "periodEnd": "2026-09-30T22:00:00.000Z", "firstDay": "2026-07-01", "lastDay": "2026-09-30", "timeZone": "Europe/Zagreb", "currency": "EUR", "dueDate": "2026-10-31", "dueAt": "2026-10-31T22:59:59.000Z", "lockableAt": "2026-09-30T22:00:00.000Z", "status": "locked", "statusChangedAt": "2026-10-02T08:00:00.000Z", "lockedAt": "2026-10-02T08:00:00.000Z", "preparedAt": null, "submittedAt": null, "reference": null, "paidAt": null, "paymentRef": null, "totals": null, "createdAt": "2026-07-01T03:00:00.000Z", "updatedAt": "2026-10-02T08:00:00.000Z", "registration": { "id": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "state": "registered", "registrationNumber": "HR12345678901", "effectiveFrom": "2026-03-31T22:00:00.000Z" }, "endsBeforeRegistration": false, "report": null, "files": [], "receipts": [], "paymentLedgerTxnIds": [], "reminders": [], "history": [ { "from": null, "to": "open", "at": "2026-07-01T03:00:00.000Z", "by": "system", "note": null }, { "from": "open", "to": "locked", "at": "2026-10-02T08:00:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null } ], "actions": { "lock": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is locked: \"lock\" needs open." }, "prepare": { "allowed": true, "code": null, "message": null }, "submit": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is locked: \"submit\" needs prepared." }, "markPaid": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is locked: \"mark_paid\" needs submitted." } } } ``` ## `filing_periods_mark_paid` **Mark a return paid.** Operation [`filing_periods.mark_paid`](https://ownrecord.io/docs/reference/filing-periods-mark-paid.md) · Legal entity level · permission `filings:write` · risk tier `compliance` · since M8 Records that the period's tax was paid (spec §21.1): the `paymentRef` (the bank transfer's reference) and the day it was paid (`paidOn`, `YYYY-MM-DD` in the period's time zone, default today). The period becomes `paid`, and the ledger moves the period's tax from tax payable to the entity's bank: `Dr tax_payable / Cr bank` per jurisdiction, one transaction per currency (kind `tax_settlement`), for the tax the report reconciled. A jurisdiction whose balance is negative (more refunded than charged) is refunded by its authority, never offset, so it isn't part of the payment. Works on a `submitted` period. Compliance tier (spec §41.4): an agent's call needs approval under the default policy. Dry-run it to see the postings without making them. Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: false` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | ID (`fp_…`) | yes | The filing period (`fp_…`). | | `paymentRef` | string | yes | The payment's reference, e.g. the bank transfer's. (1–200 characters) | | `paidOn` | string | no | The day the tax was paid (`YYYY-MM-DD`). Default: today. | | `note` | string | no | A note for the period's history, e.g. who checked the figures. (1–1000 characters) | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | | `idempotency_key` | string | no | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) | | `dry_run` | boolean | no | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`) | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours). - **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is malformed (`param` names it). - [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No filing period with this ID exists for this legal entity and mode. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity (an org key without `Ownrecord-Entity`). - [`filing_period_status_invalid`](https://ownrecord.io/docs/reference/errors.md#filing_period_status_invalid): The period isn't `submitted` (`details.status`). - [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The period changed at the same moment. Reload it and try again. - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't work on this entity's filings (tax managers, finance, owners and admins can). ### Example **The Q3 OSS tax was paid** Arguments: ```json { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "paymentRef": "HR68 1406-12345678901", "paidOn": "2026-10-16", "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy", "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21" } ``` Result `output`: ```json { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "object": "filing_period", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "reportKind": "eu_oss", "reportAvailable": true, "frequency": "quarterly", "periodKey": "2026-Q3", "periodStart": "2026-06-30T22:00:00.000Z", "periodEnd": "2026-09-30T22:00:00.000Z", "firstDay": "2026-07-01", "lastDay": "2026-09-30", "timeZone": "Europe/Zagreb", "currency": "EUR", "dueDate": "2026-10-31", "dueAt": "2026-10-31T22:59:59.000Z", "lockableAt": "2026-09-30T22:00:00.000Z", "status": "paid", "statusChangedAt": "2026-10-15T09:00:00.000Z", "lockedAt": "2026-10-02T08:00:00.000Z", "preparedAt": "2026-10-02T08:05:00.000Z", "submittedAt": "2026-10-15T09:00:00.000Z", "reference": "HR/HR12345678901/Q3.2026", "paidAt": "2026-10-15T22:00:00.000Z", "paymentRef": "HR68 1406-12345678901", "totals": { "currency": "EUR", "taxable": "1500000000", "tax": "290000000", "corrections": "-19000000", "due": "271000000", "refundable": "0" }, "createdAt": "2026-07-01T03:00:00.000Z", "updatedAt": "2026-10-15T09:00:00.000Z", "registration": { "id": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "state": "registered", "registrationNumber": "HR12345678901", "effectiveFrom": "2026-03-31T22:00:00.000Z" }, "endsBeforeRegistration": false, "report": { "kind": "eu_oss", "currency": "EUR", "rounding": "half_up", "fxRule": null, "generatedAt": "2026-10-02T08:05:00.000Z", "fx": [], "sections": [ { "id": "supplies", "title": "Supplies by member state of consumption and rate", "columns": [ { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "rate", "label": "VAT rate", "type": "rate" }, { "key": "rateKind", "label": "Rate type", "type": "text" }, { "key": "taxable", "label": "Taxable amount", "type": "money" }, { "key": "vat", "label": "VAT", "type": "money" }, { "key": "lines", "label": "Lines", "type": "count" } ], "rows": [ { "memberState": "DE", "rate": "190000", "rateKind": "standard", "taxable": "1000000000", "vat": "190000000", "lines": 8 }, { "memberState": "FR", "rate": "200000", "rateKind": "standard", "taxable": "500000000", "vat": "100000000", "lines": 3 } ] }, { "id": "corrections", "title": "Corrections of earlier periods", "columns": [ { "key": "originalPeriod", "label": "Period corrected", "type": "text" }, { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "taxable", "label": "Taxable amount", "type": "money" }, { "key": "vat", "label": "VAT", "type": "money" }, { "key": "lines", "label": "Lines", "type": "count" } ], "rows": [ { "originalPeriod": "2026-Q2", "memberState": "DE", "taxable": "-100000000", "vat": "-19000000", "lines": 1 } ] }, { "id": "balances", "title": "VAT due per member state", "columns": [ { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "supplies", "label": "VAT on supplies", "type": "money" }, { "key": "corrections", "label": "Corrections", "type": "money" }, { "key": "balance", "label": "Balance", "type": "money" } ], "rows": [ { "memberState": "DE", "supplies": "190000000", "corrections": "-19000000", "balance": "171000000" }, { "memberState": "FR", "supplies": "100000000", "corrections": "0", "balance": "100000000" } ] }, { "id": "reconciliation", "title": "Reconciliation with the ledger", "columns": [ { "key": "jurisdiction", "label": "Jurisdiction", "type": "text" }, { "key": "currency", "label": "Currency", "type": "text" }, { "key": "reportTax", "label": "Report tax", "type": "money" }, { "key": "ledgerTax", "label": "Ledger tax payable", "type": "money" }, { "key": "difference", "label": "Difference", "type": "money" } ], "rows": [ { "jurisdiction": "DE", "currency": "EUR", "reportTax": "171000000", "ledgerTax": "171000000", "difference": "0" }, { "jurisdiction": "FR", "currency": "EUR", "reportTax": "100000000", "ledgerTax": "100000000", "difference": "0" } ] } ], "reconciliation": { "matches": true, "rows": [ { "jurisdictionId": "DE", "currency": "EUR", "reportTax": "171000000", "ledgerTax": "171000000", "difference": "0" }, { "jurisdictionId": "FR", "currency": "EUR", "reportTax": "100000000", "ledgerTax": "100000000", "difference": "0" } ] }, "counts": { "lines": 12, "corrections": 1, "notReported": 0, "documents": 12 } }, "files": [ { "format": "csv", "fileId": "file_01m4tx5nj8emwbyf7y9vcf47y2", "filename": "EU_OSS_UNION-2026-Q3.csv", "contentType": "text/csv; charset=utf-8", "size": 2381, "sha256": "5d1c9d6b7f3e0a4c8b2f1e6d9a7c3b5e0f4d8a2c6b1e9f7d3a5c0b8e2f6d4a1c" }, { "format": "xlsx", "fileId": "file_01m4tx5nj8emwbyf7y9vcf47y3", "filename": "EU_OSS_UNION-2026-Q3.xlsx", "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "size": 9184, "sha256": "8a3f6c1e9d4b7a2f5c0e8d3b6a1f4c9e7d2b5a0f3c8e6d1b4a9f7c2e5d0b3a6f" } ], "receipts": [ { "kind": "file", "reference": "file_01m4tx5nj8emwbyf7y9vcf47y4", "label": "OSS portal confirmation", "addedAt": "2026-10-15T09:00:00.000Z", "addedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa" } ], "paymentLedgerTxnIds": ["txn_01m4tx5nj8emwbyf7y9vcf47y5"], "reminders": [], "history": [ { "from": null, "to": "open", "at": "2026-07-01T03:00:00.000Z", "by": "system", "note": null }, { "from": "open", "to": "locked", "at": "2026-10-02T08:00:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null }, { "from": "locked", "to": "prepared", "at": "2026-10-02T08:05:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null }, { "from": "prepared", "to": "submitted", "at": "2026-10-15T09:00:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null }, { "from": "submitted", "to": "paid", "at": "2026-10-15T09:00:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null } ], "actions": { "lock": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is paid: \"lock\" needs open." }, "prepare": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is paid: \"prepare\" needs locked or prepared." }, "submit": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is paid: \"submit\" needs prepared." }, "markPaid": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is paid: \"mark_paid\" needs submitted." } } } ``` ## `filing_periods_package` **Get a filing package.** Operation [`filing_periods.package`](https://ownrecord.io/docs/reference/filing-periods-package.md) · Legal entity level · permission `filings:read` · risk tier `read` · since M10 Returns the filing package of a prepared period (spec §41.5): everything needed to file the return in the authority's portal and pay it: - `reportFiles`: the report's CSV and XLSX (read the CSV with `filing_periods.report`; over MCP as the resource `ownrecord://entities/{entity_id}/filing-periods/{id}/report.csv`); - `summary`: taxable amounts and tax per country and rate, corrections by original period, balances; - `payment`: the amount in the filing currency, the due date and what the tax knowledge says about the authority's account and reference (null where it doesn't know yet, never guessed); - `reconciliation`: the report's tax against the ledger's tax payable for the period. Available once the period is prepared (`filing_periods.lock`, then `filing_periods.prepare`), until and after it is filed. The steps to file are in the regime's playbook. Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | ID (`fp_…`) | yes | The filing period (`fp_…`). | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Read-only:** changes nothing; `idempotency_key` is ignored. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is malformed (`param` names it). - [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No filing period with this ID exists for this legal entity and mode. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity (an org key without `Ownrecord-Entity`). - [`filing_report_not_ready`](https://ownrecord.io/docs/reference/errors.md#filing_report_not_ready): The period has no report yet: lock and prepare it first (`details.status`). - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see this entity's filings. ### Example **The package of the Q3 OSS return** Arguments: ```json { "id": "fp_01m4ttwd3veh9apbewxheq5xa7", "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy" } ``` Result `output`: ```json { "object": "filing_package", "filingPeriodId": "fp_01m4ttwd3veh9apbewxheq5xa7", "regimeId": "EU_OSS_UNION", "periodKey": "2026-Q3", "firstDay": "2026-07-01", "lastDay": "2026-09-30", "dueDate": "2026-10-31", "dueAt": "2026-10-31T22:59:59.000Z", "status": "prepared", "reportKind": "eu_oss", "reportFiles": [ { "format": "csv", "fileId": "file_01m4ttwd3veh9apbewxheq5xa5", "filename": "EU_OSS_UNION-2026-Q3.csv", "contentType": "text/csv; charset=utf-8", "size": 1824, "sha256": "9b2c7e1d0a5f4e3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c" } ], "summary": { "currency": "EUR", "rows": [ { "country": "DE", "rate": 190000, "taxable": "100000000", "tax": "19000000", "lines": 1 }, { "country": "FR", "rate": 200000, "taxable": "100000000", "tax": "20000000", "lines": 1 } ], "corrections": [], "balances": [ { "country": "DE", "supplies": "19000000", "corrections": "0", "balance": "19000000" }, { "country": "FR", "supplies": "20000000", "corrections": "0", "balance": "20000000" } ], "totals": { "taxable": "200000000", "tax": "39000000", "corrections": "0", "due": "39000000", "refundable": "0" }, "reportTotals": { "taxable": "200000000", "tax": "39000000", "corrections": "0", "due": "39000000", "refundable": "0" }, "consistent": true }, "payment": { "amount": { "amount": "39000000", "currency": "EUR", "decimal": "39.00" }, "refundable": { "amount": "0", "currency": "EUR", "decimal": "0.00" }, "dueDate": "2026-10-31", "dueAt": "2026-10-31T22:59:59.000Z", "method": null, "accountDetails": null, "referenceFormat": null, "reference": null, "notes": [ "Pay 39.00 EUR by 2026-10-31.", "Ownrecord's tax knowledge has no payment details for this return yet: use the authority's own payment instructions (see the playbook). Never pay to an account you can't verify with the authority.", "Quote the reference the authority gives when the return is filed." ] }, "reconciliation": { "matches": true, "rows": [ { "jurisdictionId": "DE", "currency": "EUR", "reportTax": "19000000", "ledgerTax": "19000000", "difference": "0" }, { "jurisdictionId": "FR", "currency": "EUR", "reportTax": "20000000", "ledgerTax": "20000000", "difference": "0" } ], "differences": [] }, "fx": [], "generatedAt": "2026-10-03T09:00:00.000Z" } ``` ## `filing_periods_prepare` **Prepare a filing period's report.** Operation [`filing_periods.prepare`](https://ownrecord.io/docs/reference/filing-periods-prepare.md) · Legal entity level · permission `filings:write` · risk tier `write` · since M8 Generates the period's report (spec §21.2) from the entity's invoices and credit notes and its ledger, never from processor data, for every brand of the entity, and stores it on the period with its CSV and XLSX files. The period becomes `prepared`. The report follows the regime (`reportKind`): - `eu_oss`: taxable amount and VAT per member state of consumption and rate in EUR (ECB rate of the period's last day, or of the next publication day), corrections of earlier periods by original period, and the balance per member state; - `eu_domestic`: domestic supplies by rate, corrections, the return values by rate, and the EC Sales List (reverse-charged services to businesses in other member states, per customer VAT ID); - `uk_vat`: the nine boxes of the UK VAT return, with sales by rate; - `ch_mwst`: turnover and tax by rate in CHF; - `us_state`: gross, taxable and exempt sales and the tax by state; - `generic`: sales and tax by jurisdiction and rate in the regime's currency. Except for `eu_oss`, other currencies are converted per the filing spec's exchange-rate rule: the ECB rate of the period's last day when it names it, else of each document's tax-point date. Credit notes for sales reported in an earlier period are corrections of that period. Sales made during a grace period are reported in the first return after the registration's effective date. Every report includes a reconciliation: its tax per jurisdiction and currency must equal the movement of the regime's tax payable accounts in the ledger for the period. If they differ, nothing is stored and the call fails with `filing_reconciliation_failed`, listing the documents that differ. Works on a `locked` period, and again on a `prepared` one until it is submitted. Write tier: tax managers, finance, owners and admins. Dry-run it to see the report without storing anything. Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | ID (`fp_…`) | yes | The filing period (`fp_…`). | | `note` | string | no | A note for the period's history, e.g. who checked the figures. (1–1000 characters) | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | | `idempotency_key` | string | no | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) | | `dry_run` | boolean | no | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`) | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours). - **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is malformed (`param` names it). - [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No filing period with this ID exists for this legal entity and mode. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity (an org key without `Ownrecord-Entity`). - [`filing_period_status_invalid`](https://ownrecord.io/docs/reference/errors.md#filing_period_status_invalid): The period isn't `locked` or `prepared` (`details.status`). - [`filing_report_kind_unsupported`](https://ownrecord.io/docs/reference/errors.md#filing_report_kind_unsupported): Ownrecord can't generate this regime's report yet (`details.report_kind`). - [`filing_registration_not_effective`](https://ownrecord.io/docs/reference/errors.md#filing_registration_not_effective): The registration is still pending: grace sales have no return until it has an effective date. - [`fx_rate_unavailable`](https://ownrecord.io/docs/reference/errors.md#fx_rate_unavailable): The ECB rates the report converts with (of the period's last day or the next publication day, or of a document's tax-point date) aren't loaded yet. Retry after the next publication. - [`filing_reconciliation_failed`](https://ownrecord.io/docs/reference/errors.md#filing_reconciliation_failed): The report's tax differs from the ledger's tax payable (`details.rows`, `details.documents`). - [`upstream_timeout`](https://ownrecord.io/docs/reference/errors.md#upstream_timeout): The file store didn't answer in time; nothing was stored. Retry. - [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The period changed at the same moment. Reload it and try again. - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't work on this entity's filings (tax managers, finance, owners and admins can). ### Example **Generate the Q3 OSS return** Arguments: ```json { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy", "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21" } ``` Result `output`: ```json { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "object": "filing_period", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "reportKind": "eu_oss", "reportAvailable": true, "frequency": "quarterly", "periodKey": "2026-Q3", "periodStart": "2026-06-30T22:00:00.000Z", "periodEnd": "2026-09-30T22:00:00.000Z", "firstDay": "2026-07-01", "lastDay": "2026-09-30", "timeZone": "Europe/Zagreb", "currency": "EUR", "dueDate": "2026-10-31", "dueAt": "2026-10-31T22:59:59.000Z", "lockableAt": "2026-09-30T22:00:00.000Z", "status": "prepared", "statusChangedAt": "2026-10-02T08:05:00.000Z", "lockedAt": "2026-10-02T08:00:00.000Z", "preparedAt": "2026-10-02T08:05:00.000Z", "submittedAt": null, "reference": null, "paidAt": null, "paymentRef": null, "totals": { "currency": "EUR", "taxable": "1500000000", "tax": "290000000", "corrections": "-19000000", "due": "271000000", "refundable": "0" }, "createdAt": "2026-07-01T03:00:00.000Z", "updatedAt": "2026-10-02T08:05:00.000Z", "registration": { "id": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "state": "registered", "registrationNumber": "HR12345678901", "effectiveFrom": "2026-03-31T22:00:00.000Z" }, "endsBeforeRegistration": false, "report": { "kind": "eu_oss", "currency": "EUR", "rounding": "half_up", "fxRule": null, "generatedAt": "2026-10-02T08:05:00.000Z", "fx": [], "sections": [ { "id": "supplies", "title": "Supplies by member state of consumption and rate", "columns": [ { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "rate", "label": "VAT rate", "type": "rate" }, { "key": "rateKind", "label": "Rate type", "type": "text" }, { "key": "taxable", "label": "Taxable amount", "type": "money" }, { "key": "vat", "label": "VAT", "type": "money" }, { "key": "lines", "label": "Lines", "type": "count" } ], "rows": [ { "memberState": "DE", "rate": "190000", "rateKind": "standard", "taxable": "1000000000", "vat": "190000000", "lines": 8 }, { "memberState": "FR", "rate": "200000", "rateKind": "standard", "taxable": "500000000", "vat": "100000000", "lines": 3 } ] }, { "id": "corrections", "title": "Corrections of earlier periods", "columns": [ { "key": "originalPeriod", "label": "Period corrected", "type": "text" }, { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "taxable", "label": "Taxable amount", "type": "money" }, { "key": "vat", "label": "VAT", "type": "money" }, { "key": "lines", "label": "Lines", "type": "count" } ], "rows": [ { "originalPeriod": "2026-Q2", "memberState": "DE", "taxable": "-100000000", "vat": "-19000000", "lines": 1 } ] }, { "id": "balances", "title": "VAT due per member state", "columns": [ { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "supplies", "label": "VAT on supplies", "type": "money" }, { "key": "corrections", "label": "Corrections", "type": "money" }, { "key": "balance", "label": "Balance", "type": "money" } ], "rows": [ { "memberState": "DE", "supplies": "190000000", "corrections": "-19000000", "balance": "171000000" }, { "memberState": "FR", "supplies": "100000000", "corrections": "0", "balance": "100000000" } ] }, { "id": "reconciliation", "title": "Reconciliation with the ledger", "columns": [ { "key": "jurisdiction", "label": "Jurisdiction", "type": "text" }, { "key": "currency", "label": "Currency", "type": "text" }, { "key": "reportTax", "label": "Report tax", "type": "money" }, { "key": "ledgerTax", "label": "Ledger tax payable", "type": "money" }, { "key": "difference", "label": "Difference", "type": "money" } ], "rows": [ { "jurisdiction": "DE", "currency": "EUR", "reportTax": "171000000", "ledgerTax": "171000000", "difference": "0" }, { "jurisdiction": "FR", "currency": "EUR", "reportTax": "100000000", "ledgerTax": "100000000", "difference": "0" } ] } ], "reconciliation": { "matches": true, "rows": [ { "jurisdictionId": "DE", "currency": "EUR", "reportTax": "171000000", "ledgerTax": "171000000", "difference": "0" }, { "jurisdictionId": "FR", "currency": "EUR", "reportTax": "100000000", "ledgerTax": "100000000", "difference": "0" } ] }, "counts": { "lines": 12, "corrections": 1, "notReported": 0, "documents": 12 } }, "files": [ { "format": "csv", "fileId": "file_01m4tx5nj8emwbyf7y9vcf47y2", "filename": "EU_OSS_UNION-2026-Q3.csv", "contentType": "text/csv; charset=utf-8", "size": 2381, "sha256": "5d1c9d6b7f3e0a4c8b2f1e6d9a7c3b5e0f4d8a2c6b1e9f7d3a5c0b8e2f6d4a1c" }, { "format": "xlsx", "fileId": "file_01m4tx5nj8emwbyf7y9vcf47y3", "filename": "EU_OSS_UNION-2026-Q3.xlsx", "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "size": 9184, "sha256": "8a3f6c1e9d4b7a2f5c0e8d3b6a1f4c9e7d2b5a0f3c8e6d1b4a9f7c2e5d0b3a6f" } ], "receipts": [], "paymentLedgerTxnIds": [], "reminders": [], "history": [ { "from": null, "to": "open", "at": "2026-07-01T03:00:00.000Z", "by": "system", "note": null }, { "from": "open", "to": "locked", "at": "2026-10-02T08:00:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null }, { "from": "locked", "to": "prepared", "at": "2026-10-02T08:05:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null } ], "actions": { "lock": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is prepared: \"lock\" needs open." }, "prepare": { "allowed": true, "code": null, "message": null }, "submit": { "allowed": true, "code": null, "message": null }, "markPaid": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is prepared: \"mark_paid\" needs submitted." } } } ``` ## `filing_periods_report` **Download a filing report.** Operation [`filing_periods.report`](https://ownrecord.io/docs/reference/filing-periods-report.md) · Legal entity level · permission `filings:read` · risk tier `read` · since M8 Returns the report file of a prepared period in `csv` or `xlsx` (spec §21.2): its name, type, size and SHA-256, and for CSV its content. The CSV is one table: a `section` column (`summary`, then the report's sections, e.g. `supplies`, `corrections`, `balances`, `amounts_by_currency` and `reconciliation` for an EU OSS return, `ec_sales_list` for an EU domestic one, `boxes` for a UK one, `sales_by_state` for a US one) followed by the sections' columns; money as decimals in the row's currency (or the report's), rates as percentages. In the console, both files download from the period's page. Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | ID (`fp_…`) | yes | The filing period (`fp_…`). | | `format` | one of `csv`, `xlsx` | yes | `csv` or `xlsx`. | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Read-only:** changes nothing; `idempotency_key` is ignored. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is malformed (`param` names it). - [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No filing period with this ID exists for this legal entity and mode. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity (an org key without `Ownrecord-Entity`). - [`filing_report_not_ready`](https://ownrecord.io/docs/reference/errors.md#filing_report_not_ready): The period has no report in that format yet: prepare it first. - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see this entity's filings. - [`entitlement_required`](https://ownrecord.io/docs/reference/errors.md#entitlement_required): A format other than CSV, on a plan with basic filing reports (`filing.reports`). ### Example **The CSV of the Q3 OSS return** Arguments: ```json { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "format": "csv", "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy" } ``` Result `output`: ```json { "object": "filing_report_file", "filingPeriodId": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "format": "csv", "fileId": "file_01m4tx5nj8emwbyf7y9vcf47y2", "filename": "EU_OSS_UNION-2026-Q3.csv", "contentType": "text/csv; charset=utf-8", "size": 2381, "sha256": "5d1c9d6b7f3e0a4c8b2f1e6d9a7c3b5e0f4d8a2c6b1e9f7d3a5c0b8e2f6d4a1c", "content": "section,item,label,value,currency,member_state,rate,…\r\nsummary,report,Report,eu_oss,,,,…\r\n…" } ``` ## `filing_periods_schedules` **List filing schedules.** Operation [`filing_periods.schedules`](https://ownrecord.io/docs/reference/filing-periods-schedules.md) · Legal entity level · permission `filings:read` · risk tier `read` · since M8 The filing schedule of each of the entity's registrations that files returns (registered, in a grace period or deregistered), or that has periods or a schedule of its own, in the mode of the request (spec §21.1). A schedule is the regime's filing spec (frequency and due rule, from the knowledge base) unless an operator set one on the registration with `filing_periods.set_schedule` (the frequency and stagger the tax authority assigned, and a due rule where the spec's can't be computed). `problem` says why no periods can be generated (`due_other`, `frequency_varies`: set a schedule; `no_filing_spec`: the knowledge base has no filing rules for the regime yet). `nextPeriodStart` and `nextDueAt` are the earliest period still to file. Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `regimeId` | string | no | Only this regime. (1–100 characters) | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Read-only:** changes nothing; `idempotency_key` is ignored. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): `regimeId` is malformed. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity (an org key without `Ownrecord-Entity`). - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see this entity's filings. ### Example **The entity's filing schedules** Arguments: ```json { "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy" } ``` Result `output`: ```json { "object": "list", "data": [ { "object": "filing_schedule", "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "registrationState": "registered", "reportKind": "eu_oss", "filingSpecId": "kn_01m4tx5nj8emwbyf7y9vcf47y8", "currency": "EUR", "frequency": "quarterly", "startMonth": 1, "due": { "kind": "end_of_following_month", "days": null, "nthDay": null, "months": null, "description": "the last day of the month after the period" }, "source": { "frequency": "filing_spec", "due": "filing_spec" }, "problem": null, "filingSpec": { "frequency": "quarterly", "due": { "kind": "end_of_following_month", "days": null, "nthDay": null, "months": null, "description": "the last day of the month after the period" } }, "registrationSchedule": null, "nextPeriodStart": "2026-06-30T22:00:00.000Z", "nextDueAt": "2026-10-31T22:59:59.000Z", "periods": 3 }, { "object": "filing_schedule", "regimeId": "GB_VAT_NETP", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47y6", "registrationState": "registered", "reportKind": "uk_vat", "filingSpecId": "kn_01m4tx5nj8emwbyf7y9vcf47y7", "currency": "GBP", "frequency": "quarterly", "startMonth": 2, "due": { "kind": "months_and_days_after_period_end", "days": 7, "nthDay": null, "months": 1, "description": "1 month and 7 days after the period ends" }, "source": { "frequency": "registration", "due": "registration" }, "problem": null, "filingSpec": { "frequency": "quarterly", "due": { "kind": "other", "days": null, "nthDay": null, "months": null, "description": "a rule Ownrecord can't compute: set a due rule on the registration" } }, "registrationSchedule": { "frequency": "quarterly", "startMonth": 2, "due": { "kind": "months_and_days_after_period_end", "days": 7, "nthDay": null, "months": 1, "description": "1 month and 7 days after the period ends" }, "note": "Stagger 2 per the VAT registration certificate", "setAt": "2026-10-20T09:00:00.000Z", "setBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa" }, "nextPeriodStart": "2026-07-31T23:00:00.000Z", "nextDueAt": "2026-12-07T23:59:59.000Z", "periods": 2 } ] } ``` ## `filing_periods_set_schedule` **Set a registration's filing schedule.** Operation [`filing_periods.set_schedule`](https://ownrecord.io/docs/reference/filing-periods-set-schedule.md) · Legal entity level · permission `filings:write` · risk tier `compliance` · since M8 Sets how often a registration files and when its returns are due, where the regime's filing spec can't say it for this taxpayer (spec §21.1): the frequency (`monthly`, `quarterly`, `annual`), the stagger (`startMonth`: a month a period starts in; 2 for UK quarters ending in January, April, July and October; 4 for a year from April) and, when the filing spec's due rule can't be computed, `due` (the UK's "1 calendar month and 7 days" is `{ "kind": "months_and_days_after_period_end", "months": 1, "days": 7 }`). Without `due` the spec's due rule applies. The filing currency, exchange-rate rule and report still come from the filing spec. The periods the registration needs up to now are created at once (later ones by the daily job). Where periods already exist, the new schedule must keep them whole: their first start and last end must be period boundaries of the new schedule (`filing_schedule_conflict`). Compliance tier (spec §41.4): tax managers, finance, owners and admins; an agent's call needs approval under the default policy. Returns the schedule and the periods created. Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------------- | --------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `regimeId` | string | yes | The registration: its regime ID (e.g. `GB_VAT_NETP`) or `regn_…` ID. (1–110 characters) | | `frequency` | one of `monthly`, `quarterly`, `annual` | yes | `monthly`, `quarterly` or `annual`. | | `startMonth` | integer | no | A month (1–12) a period starts in. Default 1: calendar months, quarters and years. (1–12) | | `due` | object | no | When each return is due. Needed when the filing spec's due rule can't be computed. | | `note` | string | no | A note for the period's history, e.g. who checked the figures. (1–1000 characters) | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | | `idempotency_key` | string | no | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) | | `dry_run` | boolean | no | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`) | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours). - **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is malformed (`param` names it). - [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The entity has no registration for this regime in this mode. - [`filing_schedule_invalid`](https://ownrecord.io/docs/reference/errors.md#filing_schedule_invalid): The schedule still can't generate periods: give `due` when the filing spec's can't be computed (`details.problem`), or the regime has no filing spec. - [`filing_schedule_conflict`](https://ownrecord.io/docs/reference/errors.md#filing_schedule_conflict): Existing periods wouldn't stay whole under the new schedule (`details.period`, `details.edge`). - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity (an org key without `Ownrecord-Entity`). - [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The registration changed at the same moment. Try again. - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't work on this entity's filings (tax managers, finance, owners and admins can). ### Example **UK VAT quarters ending in January, April, July and October** Arguments: ```json { "regimeId": "GB_VAT_NETP", "frequency": "quarterly", "startMonth": 2, "due": { "kind": "months_and_days_after_period_end", "months": 1, "days": 7 }, "note": "Stagger 2 per the VAT registration certificate", "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy", "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21" } ``` Result `output`: ```json { "object": "filing_schedule", "regimeId": "GB_VAT_NETP", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47y6", "registrationState": "registered", "reportKind": "uk_vat", "filingSpecId": "kn_01m4tx5nj8emwbyf7y9vcf47y7", "currency": "GBP", "frequency": "quarterly", "startMonth": 2, "due": { "kind": "months_and_days_after_period_end", "days": 7, "nthDay": null, "months": 1, "description": "1 month and 7 days after the period ends" }, "source": { "frequency": "registration", "due": "registration" }, "problem": null, "filingSpec": { "frequency": "quarterly", "due": { "kind": "other", "days": null, "nthDay": null, "months": null, "description": "a rule Ownrecord can't compute: set a due rule on the registration" } }, "registrationSchedule": { "frequency": "quarterly", "startMonth": 2, "due": { "kind": "months_and_days_after_period_end", "days": 7, "nthDay": null, "months": 1, "description": "1 month and 7 days after the period ends" }, "note": "Stagger 2 per the VAT registration certificate", "setAt": "2026-10-20T09:00:00.000Z", "setBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa" }, "nextPeriodStart": "2026-07-31T23:00:00.000Z", "nextDueAt": "2026-12-07T23:59:59.000Z", "periods": 2, "createdPeriods": [ { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "periodKey": "2026-05..2026-07", "dueDate": "2026-09-07" }, { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y1", "periodKey": "2026-08..2026-10", "dueDate": "2026-12-07" } ] } ``` ## `filing_periods_submit` **Mark a return submitted.** Operation [`filing_periods.submit`](https://ownrecord.io/docs/reference/filing-periods-submit.md) · Legal entity level · permission `filings:write` · risk tier `compliance` · since M8 Records that the period's return was filed with the tax authority (spec §21.1): the authority's `reference` (for the EU One-Stop Shop, the return's reference number), when it was submitted (`submittedAt`, default now) and optionally the portal's confirmation as `receipts`: documents uploaded to the period (`filing_periods.documents.upload`) or references. The period becomes `submitted`; mark it paid once the tax is paid. Ownrecord doesn't log into government portals: a person or an authorized agent files the return with the report files (spec §41.5). Works on a `prepared` period. Compliance tier (spec §41.4): an agent's call needs approval under the default policy. Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: false` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------------- | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | ID (`fp_…`) | yes | The filing period (`fp_…`). | | `reference` | string | yes | The authority's reference of the filed return. (1–200 characters) | | `submittedAt` | date-time (ISO 8601) | no | When the return was filed (ISO 8601). Default: now. | | `receipts` | array of object | no | The portal's confirmation: uploaded documents or references (optional). (at most 20 items) | | `note` | string | no | A note for the period's history, e.g. who checked the figures. (1–1000 characters) | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | | `idempotency_key` | string | no | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) | | `dry_run` | boolean | no | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`) | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours). - **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is malformed (`param` names it). - [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No filing period with this ID exists for this legal entity and mode. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity (an org key without `Ownrecord-Entity`). - [`filing_period_status_invalid`](https://ownrecord.io/docs/reference/errors.md#filing_period_status_invalid): The period isn't `prepared` (`details.status`). - [`filing_receipt_not_found`](https://ownrecord.io/docs/reference/errors.md#filing_receipt_not_found): A `file_…` receipt isn't a document of this period (`param` names it). - [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The period changed at the same moment. Reload it and try again. - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't work on this entity's filings (tax managers, finance, owners and admins can). ### Example **The Q3 OSS return was filed** Arguments: ```json { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "reference": "HR/HR12345678901/Q3.2026", "submittedAt": "2026-10-15T09:00:00.000Z", "receipts": [ { "reference": "file_01m4tx5nj8emwbyf7y9vcf47y4", "label": "OSS portal confirmation" } ], "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy", "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21" } ``` Result `output`: ```json { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "object": "filing_period", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "reportKind": "eu_oss", "reportAvailable": true, "frequency": "quarterly", "periodKey": "2026-Q3", "periodStart": "2026-06-30T22:00:00.000Z", "periodEnd": "2026-09-30T22:00:00.000Z", "firstDay": "2026-07-01", "lastDay": "2026-09-30", "timeZone": "Europe/Zagreb", "currency": "EUR", "dueDate": "2026-10-31", "dueAt": "2026-10-31T22:59:59.000Z", "lockableAt": "2026-09-30T22:00:00.000Z", "status": "submitted", "statusChangedAt": "2026-10-15T09:00:00.000Z", "lockedAt": "2026-10-02T08:00:00.000Z", "preparedAt": "2026-10-02T08:05:00.000Z", "submittedAt": "2026-10-15T09:00:00.000Z", "reference": "HR/HR12345678901/Q3.2026", "paidAt": null, "paymentRef": null, "totals": { "currency": "EUR", "taxable": "1500000000", "tax": "290000000", "corrections": "-19000000", "due": "271000000", "refundable": "0" }, "createdAt": "2026-07-01T03:00:00.000Z", "updatedAt": "2026-10-15T09:00:00.000Z", "registration": { "id": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "state": "registered", "registrationNumber": "HR12345678901", "effectiveFrom": "2026-03-31T22:00:00.000Z" }, "endsBeforeRegistration": false, "report": { "kind": "eu_oss", "currency": "EUR", "rounding": "half_up", "fxRule": null, "generatedAt": "2026-10-02T08:05:00.000Z", "fx": [], "sections": [ { "id": "supplies", "title": "Supplies by member state of consumption and rate", "columns": [ { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "rate", "label": "VAT rate", "type": "rate" }, { "key": "rateKind", "label": "Rate type", "type": "text" }, { "key": "taxable", "label": "Taxable amount", "type": "money" }, { "key": "vat", "label": "VAT", "type": "money" }, { "key": "lines", "label": "Lines", "type": "count" } ], "rows": [ { "memberState": "DE", "rate": "190000", "rateKind": "standard", "taxable": "1000000000", "vat": "190000000", "lines": 8 }, { "memberState": "FR", "rate": "200000", "rateKind": "standard", "taxable": "500000000", "vat": "100000000", "lines": 3 } ] }, { "id": "corrections", "title": "Corrections of earlier periods", "columns": [ { "key": "originalPeriod", "label": "Period corrected", "type": "text" }, { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "taxable", "label": "Taxable amount", "type": "money" }, { "key": "vat", "label": "VAT", "type": "money" }, { "key": "lines", "label": "Lines", "type": "count" } ], "rows": [ { "originalPeriod": "2026-Q2", "memberState": "DE", "taxable": "-100000000", "vat": "-19000000", "lines": 1 } ] }, { "id": "balances", "title": "VAT due per member state", "columns": [ { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "supplies", "label": "VAT on supplies", "type": "money" }, { "key": "corrections", "label": "Corrections", "type": "money" }, { "key": "balance", "label": "Balance", "type": "money" } ], "rows": [ { "memberState": "DE", "supplies": "190000000", "corrections": "-19000000", "balance": "171000000" }, { "memberState": "FR", "supplies": "100000000", "corrections": "0", "balance": "100000000" } ] }, { "id": "reconciliation", "title": "Reconciliation with the ledger", "columns": [ { "key": "jurisdiction", "label": "Jurisdiction", "type": "text" }, { "key": "currency", "label": "Currency", "type": "text" }, { "key": "reportTax", "label": "Report tax", "type": "money" }, { "key": "ledgerTax", "label": "Ledger tax payable", "type": "money" }, { "key": "difference", "label": "Difference", "type": "money" } ], "rows": [ { "jurisdiction": "DE", "currency": "EUR", "reportTax": "171000000", "ledgerTax": "171000000", "difference": "0" }, { "jurisdiction": "FR", "currency": "EUR", "reportTax": "100000000", "ledgerTax": "100000000", "difference": "0" } ] } ], "reconciliation": { "matches": true, "rows": [ { "jurisdictionId": "DE", "currency": "EUR", "reportTax": "171000000", "ledgerTax": "171000000", "difference": "0" }, { "jurisdictionId": "FR", "currency": "EUR", "reportTax": "100000000", "ledgerTax": "100000000", "difference": "0" } ] }, "counts": { "lines": 12, "corrections": 1, "notReported": 0, "documents": 12 } }, "files": [ { "format": "csv", "fileId": "file_01m4tx5nj8emwbyf7y9vcf47y2", "filename": "EU_OSS_UNION-2026-Q3.csv", "contentType": "text/csv; charset=utf-8", "size": 2381, "sha256": "5d1c9d6b7f3e0a4c8b2f1e6d9a7c3b5e0f4d8a2c6b1e9f7d3a5c0b8e2f6d4a1c" }, { "format": "xlsx", "fileId": "file_01m4tx5nj8emwbyf7y9vcf47y3", "filename": "EU_OSS_UNION-2026-Q3.xlsx", "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "size": 9184, "sha256": "8a3f6c1e9d4b7a2f5c0e8d3b6a1f4c9e7d2b5a0f3c8e6d1b4a9f7c2e5d0b3a6f" } ], "receipts": [ { "kind": "file", "reference": "file_01m4tx5nj8emwbyf7y9vcf47y4", "label": "OSS portal confirmation", "addedAt": "2026-10-15T09:00:00.000Z", "addedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa" } ], "paymentLedgerTxnIds": [], "reminders": [], "history": [ { "from": null, "to": "open", "at": "2026-07-01T03:00:00.000Z", "by": "system", "note": null }, { "from": "open", "to": "locked", "at": "2026-10-02T08:00:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null }, { "from": "locked", "to": "prepared", "at": "2026-10-02T08:05:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null }, { "from": "prepared", "to": "submitted", "at": "2026-10-15T09:00:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null } ], "actions": { "lock": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is submitted: \"lock\" needs open." }, "prepare": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is submitted: \"prepare\" needs locked or prepared." }, "submit": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is submitted: \"submit\" needs prepared." }, "markPaid": { "allowed": true, "code": null, "message": null } } } ```