Lift a hold on an organization's escalation

Ends a platform admin's hold (platform_billing.holds.set): the organization's status follows the time since its Ownrecord payment first failed again, at once (restricted after 14 days, suspended after 30, by default). Lifting an organization without a hold changes nothing. Platform admins only; recorded in the audit log.

At a glance

REST: DELETE /api/v1/platform/organizations/{orgId}/billing_hold
MCP tool: platform_billing_holds_lift
Operation ID: platform_billing.holds.lift
Scope: Platform
Permission: platform:admin
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
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

Path parameters

Field	Type	Description
`orgId`	`org_…` ID	The organization (`org_…`).

Body

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

Field	Type	Required	Description
`reason`	string	Yes	Why, for the audit log.

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"platform_billing_hold"`
`orgId`	string
`status`	one of `active`, `restricted`, `suspended`, `closing`, `closed`
`hold`	object or null
`unpaidSince`	date-time or null
`stage`	one of `active`, `restricted`, `suspended` or null
`next`	object or null
`billingOwnsStatus`	boolean

Examples

Lift a hold

HTTP

DELETE /api/v1/platform/organizations/org_01jbz3m4k5n6p7q8r9s0t1v2w3/billing_hold
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "reason": "The promised transfer didn't arrive"
}

Response (200):

JSON

{
  "object": "platform_billing_hold",
  "orgId": "org_01jbz3m4k5n6p7q8r9s0t1v2w3",
  "status": "suspended",
  "hold": null,
  "unpaidSince": "2026-10-05T09:12:00.000Z",
  "stage": "suspended",
  "next": null,
  "billingOwnsStatus": true
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	The organization ID, stage, reason or date is missing or malformed.	Fix the fields listed in `details.issues` and send the request again.
`platform_billing_unavailable`	409	Ownrecord's plans aren't set up on this installation yet.	A platform admin runs `pnpm platform:bootstrap`, which creates the plans, prices and features of data/platform/plans.yaml. Try again afterwards.
`resource_not_found`	404	There is no such organization.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`permission_denied`	403	Only a platform_admin holds an organization's escalation.	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, idempotency_key_reused, idempotency_in_progress, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Lift a hold#

Errors#