Set a registration's filing schedule

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`	400	A field is malformed (`param` names it).	Fix the fields listed in `details.issues` and send the request again.
`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`	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`	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`	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`	409	The registration changed at the same moment. Try again.	Fetch the object again and retry the change.
`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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

UK VAT quarters ending in January, April, July and October#

Errors#