# Get a filing package

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

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`](https://ownrecord.io/docs/reference/errors.md#validation_failed)             | 400         | A field is malformed (`param` names it).                                    | Fix the fields listed in `details.issues` and send the request again.                                                                              |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found)           | 404         | No filing period with this ID exists for this legal entity and mode.        | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.                                               |
| [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required)                   | 400         | The request names no legal entity (an org key without `Ownrecord-Entity`).  | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). |
| [`filing_report_not_ready`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).