Get a filing package · Ownrecord docs

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.

At a glance

REST: GET /api/v1/filing_periods/{id}/package
MCP tool: filing_periods_package
Operation ID: filing_periods.package
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: M10

Request

Path parameters

Field	Type	Description
`id`	`fp_…` ID	The filing period (`fp_…`).

Query parameters

This operation takes no query parameters.

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"filing_package"`
`filingPeriodId`	`fp_…` ID
`regimeId`	string
`periodKey`	string
`firstDay`	string
`lastDay`	string
`dueDate`	string
`dueAt`	date-time
`status`	string
`reportKind`	string
`reportFiles`	array of object
`reportFiles[].format`	string
`reportFiles[].fileId`	`file_…` ID
`reportFiles[].filename`	string
`reportFiles[].contentType`	string
`reportFiles[].size`	integer (at least 0)
`reportFiles[].sha256`	string
`summary`	object
`summary.currency`	string
`summary.rows`	array of object
`summary.rows[].country`	string
`summary.rows[].rate`	integer or null
`summary.rows[].taxable`	integer string
`summary.rows[].tax`	integer string
`summary.rows[].lines`	integer (at least 0)
`summary.corrections`	array of object
`summary.corrections[].country`	string
`summary.corrections[].rate`	integer or null
`summary.corrections[].taxable`	integer string
`summary.corrections[].tax`	integer string
`summary.corrections[].lines`	integer (at least 0)
`summary.corrections[].originalPeriod`	string
`summary.balances`	array of object
`summary.balances[].country`	string
`summary.balances[].supplies`	integer string
`summary.balances[].corrections`	integer string
`summary.balances[].balance`	integer string
`summary.totals`	object
`summary.totals.taxable`	integer string
`summary.totals.tax`	integer string
`summary.totals.corrections`	integer string
`summary.totals.due`	integer string
`summary.totals.refundable`	integer string
`summary.reportTotals`	object
`summary.reportTotals.taxable`	integer string
`summary.reportTotals.tax`	integer string
`summary.reportTotals.corrections`	integer string
`summary.reportTotals.due`	integer string
`summary.reportTotals.refundable`	integer string
`summary.consistent`	boolean
`payment`	object
`payment.amount`	object
`payment.amount.amount`	integer string
`payment.amount.currency`	string
`payment.amount.decimal`	string
`payment.refundable`	object
`payment.refundable.amount`	integer string
`payment.refundable.currency`	string
`payment.refundable.decimal`	string
`payment.dueDate`	string
`payment.dueAt`	date-time
`payment.method`	string or null
`payment.accountDetails`	string or null
`payment.referenceFormat`	string or null
`payment.reference`	string or null
`payment.notes`	array of string
`reconciliation`	object
`reconciliation.matches`	boolean
`reconciliation.rows`	array of object
`reconciliation.rows[].jurisdictionId`	string
`reconciliation.rows[].currency`	string
`reconciliation.rows[].reportTax`	integer string
`reconciliation.rows[].ledgerTax`	integer string
`reconciliation.rows[].difference`	integer string
`reconciliation.differences`	array of object
`reconciliation.differences[].jurisdictionId`	string
`reconciliation.differences[].currency`	string
`reconciliation.differences[].documentId`	string
`reconciliation.differences[].documentNumber`	string or null
`reconciliation.differences[].reportTax`	integer string
`reconciliation.differences[].ledgerTax`	integer string
`reconciliation.differences[].difference`	integer string
`fx`	array of object
`fx[].periodKey`	string
`fx[].forDate`	string
`fx[].date`	string
`fx[].source`	string
`fx[].rates`	object
`generatedAt`	date-time

Examples

The package of the Q3 OSS return

HTTP

GET /api/v1/filing_periods/fp_01m4ttwd3veh9apbewxheq5xa7/package
Authorization: Bearer or_test_…

Response (200):

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

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A field is malformed (`param` names it).	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	No filing period with this ID exists for this legal entity and mode.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`scope_required`	400	The request names no legal entity (an org key without `Ownrecord-Entity`).	Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`).
`filing_report_not_ready`	409	The period has no report yet: lock and prepare it first (`details.status`).	Prepare the period first (`filing_periods.prepare`), then download its report.
`permission_denied`	403	You 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.

At a glance#

Request#

Path parameters#

Query parameters#

Response#

Examples#

The package of the Q3 OSS return#

Errors#