List filing periods · Ownrecord docs

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.

At a glance

REST: GET /api/v1/filing_periods
MCP tool: filing_periods_list
Operation ID: filing_periods.list
Scope: Legal entity
Permission: filings:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Pagination: limit (at most 100) and starting_after
Authentication: API key with the filings:read scope
Since: M8

Request

Query parameters

Field	Type	Required	Description
`regimeId`	string	No	Only this regime's periods, e.g. `EU_OSS_UNION`.
`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 (1 to 100)	No	Page size, 1 to 100 (default 10).
`starting_after`	`fp_…` ID	No	The `next_cursor` of the previous page.

Response

200 OK with a JSON object, a page of the list (newest first):

Field	Type	Description
`object`	`"list"`
`data`	array of object
`data[].id`	`fp_…` ID
`data[].object`	`"filing_period"`
`data[].entityId`	`ent_…` ID
`data[].livemode`	boolean
`data[].regimeId`	string
`data[].registrationId`	`regn_…` ID
`data[].reportKind`	one of `eu_oss`, `eu_domestic`, `uk_vat`, `ch_mwst`, `generic`, `us_state`
`data[].reportAvailable`	boolean
`data[].frequency`	one of `monthly`, `quarterly`, `annual`
`data[].periodKey`	string	The period: "2026-Q3", "2026-07" or "2026".
`data[].periodStart`	date-time
`data[].periodEnd`	date-time	The end (exclusive): the next period's first local midnight.
`data[].firstDay`	string
`data[].lastDay`	string
`data[].timeZone`	string
`data[].currency`	string
`data[].dueDate`	string
`data[].dueAt`	date-time	23:59:59 local time on the due date.
`data[].lockableAt`	date-time
`data[].status`	one of `open`, `locked`, `prepared`, `submitted`, `paid`
`data[].statusChangedAt`	date-time
`data[].lockedAt`	date-time or null
`data[].preparedAt`	date-time or null
`data[].submittedAt`	date-time or null
`data[].reference`	string or null
`data[].paidAt`	date-time or null
`data[].paymentRef`	string or null
`data[].totals`	object or null
`data[].createdAt`	date-time
`data[].updatedAt`	date-time
`has_more`	boolean
`next_cursor`	`fp_…` ID or null

Examples

The OSS returns still to file

HTTP

GET /api/v1/filing_periods?regimeId=EU_OSS_UNION&status=open&status=locked&status=prepared&limit=10
Authorization: Bearer or_test_…

Response (200):

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
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A filter or the page size is malformed (`details.issues`).	Fix the fields listed in `details.issues` and send the request again.
`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`).
`permission_denied`	403	You can't see this entity's filings (brand-scoped members never can).	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, resource_not_found, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Query parameters#

Response#

Examples#

The OSS returns still to file#

Errors#