# PATCH /api/v1/accounting-periods/settings

> Update accounting period settings

- **Tag:** accounting-periods
- **Operation ID:** `update_accounting_period_settings`

## Description

Turn automatic period creation on or off. When on, the daily job opens the period of the month that just ended and of the current month if they are missing. auto_close_prep_enabled / auto_close_prep_day opt the business in to automatic close preparation: the daily job dry-runs Regent's close checks and files the close as a pending change; nothing closes without approval. agent_close_business_day (1-23, -1 = last; null or 0 = off) is the business day the Agent window starts the close of the month that just ended.

## Authentication

Bearer token in `Authorization` header.
Required header: `x-business-id: <business uuid>`.

## Request body

Schema: `AccountingPeriodSettings`

- `auto_create_periods` (boolean · required) — When true, a nightly job opens the period for the month that just ended and the current month (UTC), with its checklist and blockers initialised, and emits accounting_period.created.
- `auto_close_prep_enabled` (boolean) — When true, a daily job prepares the month-end close on auto_close_prep_day: it dry-runs Regent's close checks for the month that just ended, files the close as a pending change for a person to approve, and notifies the owner/admins. Nothing is closed without that approval. Omit on update to leave unchanged.
- `auto_close_prep_day` (integer) — Day of the month (1-28, UTC) the close preparation runs. Omit on update to leave unchanged.
- `agent_close_business_day` (integer) — Business day of the month (1-23, -1 = the last one) on which the Agent window starts closing the month that just ended: DayZero sends close.window_opened that day (Fed bank-holiday calendar, New York date). null = off. On update: omit to leave unchanged, send null or 0 to turn it off.

## Responses

### 200 — Successful Response

Schema: `SuccessEnvelope_AccountingPeriodSettings_`

- `success` (boolean)
- `message` (string)
- `code` (string)
- `data` (AccountingPeriodSettings)

### 400 — Bad Request - Invalid input

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### 401 — Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### 403 — Forbidden - Insufficient permissions

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### 404 — Not Found - Resource does not exist

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### 422 — Validation Error

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

## Code samples

### cURL

```bash
curl -X PATCH 'https://api.ondayzero.com/api/v1/accounting-periods/settings' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "auto_create_periods": false
}'
```

### JavaScript

```javascript
const response = await fetch('https://api.ondayzero.com/api/v1/accounting-periods/settings', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "auto_create_periods": false
}),
});
const data = await response.json();
```

### Python

```python
import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

payload = {'auto_create_periods': False}

response = httpx.patch("https://api.ondayzero.com/api/v1/accounting-periods/settings", headers=headers, json=payload)
data = response.json()
```

## See also

- HTML version: https://www.ondayzero.com/docs/reference/accounting-periods/update-accounting-period-settings
- OpenAPI slice: https://www.ondayzero.com/docs/reference/accounting-periods/update-accounting-period-settings/openapi.json
- Other endpoints in **accounting-periods**: https://www.ondayzero.com/docs/reference/accounting-periods (markdown bundle: https://www.ondayzero.com/docs/reference/accounting-periods.md, OpenAPI: https://www.ondayzero.com/docs/reference/accounting-periods/openapi.json)
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md