Change the platform billing thresholds

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`	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`	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`	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`	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`	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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, resource_not_found, idempotency_key_reused, idempotency_in_progress, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

Suspend after 45 days#

Errors#