# Mark a return paid > The filing_periods.mark_paid operation: POST /api/v1/filing_periods/{id}/mark_paid in the REST API and the filing_periods_mark_paid tool in the MCP server. 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. ## At a glance - **REST:** `POST /api/v1/filing_periods/{id}/mark_paid` - **MCP tool:** `filing_periods_mark_paid` - **Operation ID:** `filing_periods.mark_paid` - **Scope:** Legal entity - **Permission:** `filings:write` - **Risk tier:** `compliance` - **Dry run:** Supported (send `Ownrecord-Dry-Run: true`) - **Idempotency:** `Idempotency-Key` required - **Modes:** Test and live - **Authentication:** API key with the `filings:write` scope - **Since:** M8 ## Request ### Path parameters | Field | Type | Description | | ----- | --------- | --------------------------- | | `id` | `fp_…` ID | The filing period (`fp_…`). | ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------- | | `paymentRef` | string | Yes | The payment's reference, e.g. the bank transfer's. | | `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. | ## Response `200 OK` with a JSON object: | Field | Type | Description | | -------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ | | `id` | `fp_…` ID | | | `object` | `"filing_period"` | | | `entityId` | `ent_…` ID | | | `livemode` | boolean | | | `regimeId` | string | | | `registrationId` | `regn_…` ID | | | `reportKind` | one of `eu_oss`, `eu_domestic`, `uk_vat`, `ch_mwst`, `generic`, `us_state` | | | `reportAvailable` | boolean | | | `frequency` | one of `monthly`, `quarterly`, `annual` | | | `periodKey` | string | The period: "2026-Q3", "2026-07" or "2026". | | `periodStart` | date-time | | | `periodEnd` | date-time | The end (exclusive): the next period's first local midnight. | | `firstDay` | string | | | `lastDay` | string | | | `timeZone` | string | | | `currency` | string | | | `dueDate` | string | | | `dueAt` | date-time | 23:59:59 local time on the due date. | | `lockableAt` | date-time | | | `status` | one of `open`, `locked`, `prepared`, `submitted`, `paid` | | | `statusChangedAt` | date-time | | | `lockedAt` | date-time or null | | | `preparedAt` | date-time or null | | | `submittedAt` | date-time or null | | | `reference` | string or null | | | `paidAt` | date-time or null | | | `paymentRef` | string or null | | | `totals` | object or null | | | `createdAt` | date-time | | | `updatedAt` | date-time | | | `registration` | object or null | | | `endsBeforeRegistration` | boolean | | | `report` | object or null | | | `files` | array of object | | | `files[].format` | one of `csv`, `xlsx`, `xml` | | | `files[].fileId` | `file_…` ID | | | `files[].filename` | string | | | `files[].contentType` | string | | | `files[].size` | integer | | | `files[].sha256` | string | | | `receipts` | array of object | | | `receipts[].kind` | one of `file`, `reference` | | | `receipts[].reference` | string | | | `receipts[].label` | string or null | | | `receipts[].addedAt` | date-time | | | `receipts[].addedBy` | string | | | `paymentLedgerTxnIds` | array of `txn_…` ID | | | `reminders` | array of object | | | `reminders[].code` | string | | | `reminders[].at` | date-time | | | `reminders[].skipped` | boolean | | | `history` | array of object | | | `history[].from` | one of `open`, `locked`, `prepared`, `submitted`, `paid` or null | | | `history[].to` | one of `open`, `locked`, `prepared`, `submitted`, `paid` | | | `history[].at` | date-time | | | `history[].by` | string | | | `history[].note` | string or null | | | `actions` | object | | | `actions.lock` | object | | | `actions.lock.allowed` | boolean | | | `actions.lock.code` | string or null | | | `actions.lock.message` | string or null | | | `actions.prepare` | object | | | `actions.prepare.allowed` | boolean | | | `actions.prepare.code` | string or null | | | `actions.prepare.message` | string or null | | | `actions.submit` | object | | | `actions.submit.allowed` | boolean | | | `actions.submit.code` | string or null | | | `actions.submit.message` | string or null | | | `actions.markPaid` | object | | | `actions.markPaid.allowed` | boolean | | | `actions.markPaid.code` | string or null | | | `actions.markPaid.message` | string or null | | ## Examples ### The Q3 OSS tax was paid ```http POST /api/v1/filing_periods/fp_01m4tx5nj8emwbyf7y9vcf47y0/mark_paid Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/json { "paymentRef": "HR68 1406-12345678901", "paidOn": "2026-10-16" } ``` Response (`200`): ```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." } } } ``` ## Errors | Code | HTTP status | When | What to do | | ------------------------------------------------------------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A field is malformed (`param` names it). | Fix the fields listed in `details.issues` and send the request again. | | [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404 | No filing period with this ID exists for this legal entity and mode. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. | | [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required) | 400 | The request names no legal entity (an org key without `Ownrecord-Entity`). | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). | | [`filing_period_status_invalid`](https://ownrecord.io/docs/reference/errors.md#filing_period_status_invalid) | 409 | The period isn't `submitted` (`details.status`). | Reload the period and check its `status`: `details.allowed_from` lists the statuses the action needs. Periods go open → locked → prepared → submitted → paid. | | [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict) | 409 | The period changed at the same moment. Reload it and try again. | Fetch the object again and retry the change. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't work on this entity's filings (tax managers, finance, owners and admins can). | Ask an organization owner or admin for a role or scope that allows this action. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).