Skip to content
Docs
APISign inStart free

Get a filing period

The filing_periods.get operation: GET /api/v1/filing_periods/{id} in the REST API and the filing_periods_get tool in the MCP server.

GET/api/v1/filing_periods/{id}

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

At a glance

  • REST: GET /api/v1/filing_periods/{id}
  • MCP tool: filing_periods_get
  • Operation ID: filing_periods.get
  • Scope: Legal entity
  • Permission: filings:read
  • Risk tier: read
  • Dry run: Not supported
  • Idempotency: Not needed (read only)
  • Modes: Test and live
  • Authentication: API key with the filings:read scope
  • Since: M8

Request

Path parameters

FieldTypeDescription
idfp_… IDThe filing period (fp_…).

Query parameters

This operation takes no query parameters.

Response

200 OK with a JSON object:

FieldTypeDescription
idfp_… ID
object"filing_period"
entityIdent_… ID
livemodeboolean
regimeIdstring
registrationIdregn_… ID
reportKindone of eu_oss, eu_domestic, uk_vat, ch_mwst, generic, us_state
reportAvailableboolean
frequencyone of monthly, quarterly, annual
periodKeystringThe period: "2026-Q3", "2026-07" or "2026".
periodStartdate-time
periodEnddate-timeThe end (exclusive): the next period's first local midnight.
firstDaystring
lastDaystring
timeZonestring
currencystring
dueDatestring
dueAtdate-time23:59:59 local time on the due date.
lockableAtdate-time
statusone of open, locked, prepared, submitted, paid
statusChangedAtdate-time
lockedAtdate-time or null
preparedAtdate-time or null
submittedAtdate-time or null
referencestring or null
paidAtdate-time or null
paymentRefstring or null
totalsobject or null
createdAtdate-time
updatedAtdate-time
registrationobject or null
endsBeforeRegistrationboolean
reportobject or null
filesarray of object
files[].formatone of csv, xlsx, xml
files[].fileIdfile_… ID
files[].filenamestring
files[].contentTypestring
files[].sizeinteger
files[].sha256string
receiptsarray of object
receipts[].kindone of file, reference
receipts[].referencestring
receipts[].labelstring or null
receipts[].addedAtdate-time
receipts[].addedBystring
paymentLedgerTxnIdsarray of txn_… ID
remindersarray of object
reminders[].codestring
reminders[].atdate-time
reminders[].skippedboolean
historyarray of object
history[].fromone of open, locked, prepared, submitted, paid or null
history[].toone of open, locked, prepared, submitted, paid
history[].atdate-time
history[].bystring
history[].notestring or null
actionsobject
actions.lockobject
actions.lock.allowedboolean
actions.lock.codestring or null
actions.lock.messagestring or null
actions.prepareobject
actions.prepare.allowedboolean
actions.prepare.codestring or null
actions.prepare.messagestring or null
actions.submitobject
actions.submit.allowedboolean
actions.submit.codestring or null
actions.submit.messagestring or null
actions.markPaidobject
actions.markPaid.allowedboolean
actions.markPaid.codestring or null
actions.markPaid.messagestring or null

Examples

A prepared OSS return

HTTP
GET /api/v1/filing_periods/fp_01m4tx5nj8emwbyf7y9vcf47y0
Authorization: Bearer or_test_…

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": "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."
    }
  }
}

Errors

CodeHTTP statusWhenWhat to do
validation_failed400A field is malformed (param names it).Fix the fields listed in details.issues and send the request again.
resource_not_found404No 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_required400The 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_denied403You can't see this entity's filings.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, dry_run_not_supported, rate_limited, internal_error.