# Change the platform billing thresholds

> The platform_billing.settings.update operation: PATCH /api/v1/platform/billing_settings in the REST API and the platform_billing_settings_update tool in the MCP server.

Changes how many days after a failed Ownrecord payment an organization is restricted (`restrictAfterDays`,
default 14) and suspended (`suspendAfterDays`, default 30), from 1 to 60 days, restriction first. Organizations
move at the next escalation pass. The platform brand's own billing settings follow: payment retries and
entitlements last until the suspension. Platform admins only; audited.

## At a glance

- **REST:** `PATCH /api/v1/platform/billing_settings`
- **MCP tool:** `platform_billing_settings_update`
- **Operation ID:** `platform_billing.settings.update`
- **Scope:** Platform
- **Permission:** `platform:admin`
- **Risk tier:** `write`
- **Dry run:** Not supported
- **Idempotency:** `Idempotency-Key` optional
- **Modes:** Test and live
- **Authentication:** API key with the `platform:admin` scope
- **Fresh sign-in:** In the console, a sign-in within the last 15 minutes
- **Since:** M12

## Request

### Body

A JSON object (`Content-Type: application/json`):

| Field               | Type              | Required | Description |
| ------------------- | ----------------- | -------- | ----------- |
| `restrictAfterDays` | integer (1 to 60) | No       |             |
| `suspendAfterDays`  | integer (1 to 60) | No       |             |

## Response

`200 OK` with a JSON object:

| Field                | Type                          | Description |
| -------------------- | ----------------------------- | ----------- |
| `object`             | `"platform_billing_settings"` |             |
| `restrictAfterDays`  | integer                       |             |
| `suspendAfterDays`   | integer                       |             |
| `livemode`           | boolean                       |             |
| `defaultPlanPriceId` | string or null                |             |

## Examples

### Suspend after 45 days

```http
PATCH /api/v1/platform/billing_settings
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "suspendAfterDays": 45
}
```

Response (`200`):

```json
{
  "object": "platform_billing_settings",
  "restrictAfterDays": 14,
  "suspendAfterDays": 45,
  "livemode": true,
  "defaultPlanPriceId": "price_01jbz3m4k5n6p7q8r9s0t1v2w8"
}
```

## Errors

| Code                                                                                                                       | HTTP status | When                                                                         | What to do                                                                                                                                       |
| -------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)                                     | 400         | A threshold is missing or not a whole number.                                | Fix the fields listed in `details.issues` and send the request again.                                                                            |
| [`platform_billing_thresholds_invalid`](https://ownrecord.io/docs/reference/errors.md#platform_billing_thresholds_invalid) | 400         | The thresholds are outside 1–60 days or not in order.                        | Use whole days from 1 to 60, with `suspendAfterDays` later than `restrictAfterDays` (the defaults are 14 and 30).                                |
| [`platform_billing_unavailable`](https://ownrecord.io/docs/reference/errors.md#platform_billing_unavailable)               | 409         | The platform bootstrap hasn't run yet.                                       | A platform admin runs `pnpm platform:bootstrap`, which creates the plans, prices and features of data/platform/plans.yaml. Try again afterwards. |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)                                     | 403         | Only platform staff read, and only a platform_admin changes, these settings. | Ask an organization owner or admin for a role or scope that allows this action.                                                                  |
| [`fresh_auth_required`](https://ownrecord.io/docs/reference/errors.md#fresh_auth_required)                                 | 403         | Your last sign-in is older than 15 minutes: sign in again first.             | Sign in again, then repeat the action within 15 minutes.                                                                                         |

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), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`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), [`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).