Filing periods tools · Ownrecord docs

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 · 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: A filter is malformed (param names it).
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 · 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: A field is malformed (param names it).
resource_not_found: No filing period with this ID exists for this legal entity and mode.
scope_required: The request names no legal entity (an org key without Ownrecord-Entity).
upstream_timeout: The file store didn't answer in time; nothing was recorded. Retry.
version_conflict: The period changed at the same moment. Reload it and try again.
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 · 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: A field is malformed (param names it).
resource_not_found: No filing period with this ID exists for this legal entity and mode.
scope_required: The request names no legal entity (an org key without Ownrecord-Entity).
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 · 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: A filter or the page size is malformed (details.issues).
scope_required: The request names no legal entity (an org key without Ownrecord-Entity).
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 · 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: A field is malformed (param names it).
resource_not_found: No filing period with this ID exists for this legal entity and mode.
scope_required: The request names no legal entity (an org key without Ownrecord-Entity).
filing_period_status_invalid: The period isn't open (details.status).
filing_period_not_ended: The period isn't over yet (details.lockable_at).
version_conflict: The period changed at the same moment. Reload it and try again.
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 · 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: A field is malformed (param names it).
resource_not_found: No filing period with this ID exists for this legal entity and mode.
scope_required: The request names no legal entity (an org key without Ownrecord-Entity).
filing_period_status_invalid: The period isn't submitted (details.status).
version_conflict: The period changed at the same moment. Reload it and try again.
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 · 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: A field is malformed (param names it).
resource_not_found: No filing period with this ID exists for this legal entity and mode.
scope_required: The request names no legal entity (an org key without Ownrecord-Entity).
filing_report_not_ready: The period has no report yet: lock and prepare it first (details.status).
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 · 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: A field is malformed (param names it).
resource_not_found: No filing period with this ID exists for this legal entity and mode.
scope_required: The request names no legal entity (an org key without Ownrecord-Entity).
filing_period_status_invalid: The period isn't locked or prepared (details.status).
filing_report_kind_unsupported: Ownrecord can't generate this regime's report yet (details.report_kind).
filing_registration_not_effective: The registration is still pending: grace sales have no return until it has an effective date.
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: The report's tax differs from the ledger's tax payable (details.rows, details.documents).
upstream_timeout: The file store didn't answer in time; nothing was stored. Retry.
version_conflict: The period changed at the same moment. Reload it and try again.
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 · 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: A field is malformed (param names it).
resource_not_found: No filing period with this ID exists for this legal entity and mode.
scope_required: The request names no legal entity (an org key without Ownrecord-Entity).
filing_report_not_ready: The period has no report in that format yet: prepare it first.
permission_denied: You can't see this entity's filings.
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 · 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: regimeId is malformed.
scope_required: The request names no legal entity (an org key without Ownrecord-Entity).
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 · 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: A field is malformed (param names it).
resource_not_found: The entity has no registration for this regime in this mode.
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: Existing periods wouldn't stay whole under the new schedule (details.period, details.edge).
scope_required: The request names no legal entity (an org key without Ownrecord-Entity).
version_conflict: The registration changed at the same moment. Try again.
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 · 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: A field is malformed (param names it).
resource_not_found: No filing period with this ID exists for this legal entity and mode.
scope_required: The request names no legal entity (an org key without Ownrecord-Entity).
filing_period_status_invalid: The period isn't prepared (details.status).
filing_receipt_not_found: A file_… receipt isn't a document of this period (param names it).
version_conflict: The period changed at the same moment. Reload it and try again.
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
    }
  }
}

filing_periods_calendar#

Arguments#

Errors#

Example#

filing_periods_documents_upload#

Arguments#

Errors#

Example#

filing_periods_get#

Arguments#

Errors#

Example#

filing_periods_list#

Arguments#

Errors#

Example#

filing_periods_lock#

Arguments#

Errors#

Example#

filing_periods_mark_paid#

Arguments#

Errors#

Example#

filing_periods_package#

Arguments#

Errors#

Example#

filing_periods_prepare#

Arguments#

Errors#

Example#

filing_periods_report#

Arguments#

Errors#

Example#

filing_periods_schedules#

Arguments#

Errors#

Example#

filing_periods_set_schedule#

Arguments#

Errors#

Example#

filing_periods_submit#

Arguments#

Errors#

Example#

`filing_periods_calendar`

Arguments

Errors

Example

`filing_periods_documents_upload`

Arguments

Errors

Example

`filing_periods_get`

Arguments

Errors

Example

`filing_periods_list`

Arguments

Errors

Example

`filing_periods_lock`

Arguments

Errors

Example

`filing_periods_mark_paid`

Arguments

Errors

Example

`filing_periods_package`

Arguments

Errors

Example

`filing_periods_prepare`

Arguments

Errors

Example

`filing_periods_report`

Arguments

Errors

Example

`filing_periods_schedules`

Arguments

Errors

Example

`filing_periods_set_schedule`

Arguments

Errors

Example

`filing_periods_submit`

Arguments

Errors

Example