# Set a registration's filing schedule > The filing_periods.set_schedule operation: POST /api/v1/filing_schedules/{regimeId} in the REST API and the filing_periods_set_schedule tool in the MCP server. 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. ## At a glance - **REST:** `POST /api/v1/filing_schedules/{regimeId}` - **MCP tool:** `filing_periods_set_schedule` - **Operation ID:** `filing_periods.set_schedule` - **Scope:** Legal entity - **Permission:** `filings:write` - **Risk tier:** `compliance` - **Dry run:** Supported (send `Ownrecord-Dry-Run: true`) - **Idempotency:** `Idempotency-Key` required - **Modes:** Test and live - **Authentication:** API key with the `filings:write` scope - **Since:** M8 ## Request ### Path parameters | Field | Type | Description | | ---------- | ------ | -------------------------------------------------------------------- | | `regimeId` | string | The registration: its regime ID (e.g. `GB_VAT_NETP`) or `regn_…` ID. | ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | ------------ | -------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `frequency` | one of `monthly`, `quarterly`, `annual` | Yes | `monthly`, `quarterly` or `annual`. | | `startMonth` | integer (1 to 12) | No | A month (1–12) a period starts in. Default 1: calendar months, quarters and years. | | `due` | object | No | When each return is due. Needed when the filing spec's due rule can't be computed. | | `due.kind` | one of `days_after_period_end`, `end_of_following_month`, `nth_day_of_following_month`, `months_and_days_after_period_end` | Yes | `days_after_period_end` (`days`), `end_of_following_month`, `nth_day_of_following_month` (`nthDay`) or `months_and_days_after_period_end` (`months`, `days`: the UK's one month and seven days). | | `due.days` | integer (0 to 366) | No | | | `due.nthDay` | integer (1 to 31) | No | | | `due.months` | integer (0 to 12) | No | | | `note` | string | No | A note for the period's history, e.g. who checked the figures. | ## Response `200 OK` with a JSON object: | Field | Type | Description | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `object` | `"filing_schedule"` | | | `regimeId` | string | | | `registrationId` | `regn_…` ID | | | `registrationState` | one of `not_applicable`, `monitored`, `pre_registration`, `grace`, `registered`, `blocked_b2c`, `deregistered` | | | `reportKind` | one of `eu_oss`, `eu_domestic`, `uk_vat`, `ch_mwst`, `generic`, `us_state` or null | | | `filingSpecId` | string or null | | | `currency` | string or null | | | `frequency` | one of `monthly`, `quarterly`, `annual` or null | | | `startMonth` | integer or null | | | `due` | object or null | | | `source` | object or null | | | `problem` | one of `no_filing_spec`, `frequency_varies`, `due_other`, `due_days_missing`, `due_nth_day_missing`, `due_months_missing`, `regime_missing` or null | | | `filingSpec` | object or null | | | `registrationSchedule` | object or null | | | `nextPeriodStart` | date-time or null | | | `nextDueAt` | date-time or null | | | `periods` | integer | | | `createdPeriods` | array of object | | | `createdPeriods[].id` | `fp_…` ID | | | `createdPeriods[].periodKey` | string | | | `createdPeriods[].dueDate` | string | | ## Examples ### UK VAT quarters ending in January, April, July and October ```http POST /api/v1/filing_schedules/GB_VAT_NETP Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/json { "frequency": "quarterly", "startMonth": 2, "due": { "kind": "months_and_days_after_period_end", "months": 1, "days": 7 }, "note": "Stagger 2 per the VAT registration certificate" } ``` Response (`200`): ```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" } ] } ``` ## 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 | The entity has no registration for this regime in this mode. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. | | [`filing_schedule_invalid`](https://ownrecord.io/docs/reference/errors.md#filing_schedule_invalid) | 400 | 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. | Give a due rule (`due`) when the regime's filing spec has none Ownrecord can compute (`details.problem`: `due_other`), or complete it (`due_days_missing`, `due_nth_day_missing`, `due_months_missing`). A regime without a filing spec (`no_filing_spec`) needs its filing rules in the knowledge base first. | | [`filing_schedule_conflict`](https://ownrecord.io/docs/reference/errors.md#filing_schedule_conflict) | 409 | Existing periods wouldn't stay whole under the new schedule (`details.period`, `details.edge`). | Choose a frequency and stagger whose periods start where the first existing period starts and end where the last one ends (`details.period`, `details.edge`, `details.at`). | | [`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`). | | [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict) | 409 | The registration changed at the same moment. Try again. | Fetch the object again and retry the change. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't work on this entity's filings (tax managers, finance, owners and admins can). | 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), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).