Get an organization's unpaid-plan escalation

Returns where an organization's unpaid-plan escalation stands (spec §37.5): its status, when its Ownrecord subscription became unpaid, the stage the escalation set, the next change if it stays unpaid, and a platform admin's hold. billingOwnsStatus is false while the organization is suspended for abuse or is closing or closed: the escalation then changes nothing. Platform staff only.

At a glance

REST: GET /api/v1/platform/organizations/{orgId}/billing_hold
MCP tool: platform_billing_holds_get
Operation ID: platform_billing.holds.get
Scope: Platform
Permission: platform:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Authentication: API key with the platform:read scope
Since: M12

Request

Path parameters

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

Query parameters

This operation takes no query parameters.

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

Restricted and held there until a bank transfer arrives

HTTP

GET /api/v1/platform/organizations/org_01jbz3m4k5n6p7q8r9s0t1v2w3/billing_hold
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "platform_billing_hold",
  "orgId": "org_01jbz3m4k5n6p7q8r9s0t1v2w3",
  "status": "restricted",
  "hold": {
    "stage": "restricted",
    "until": "2026-11-15T00:00:00.000Z",
    "reason": "Paying by bank transfer; payment confirmed for 10 November",
    "setBy": "usr_01jbz3m4k5n6p7q8r9s0t1v2w7"
  },
  "unpaidSince": "2026-10-05T09:12:00.000Z",
  "stage": "restricted",
  "next": {
    "stage": "suspended",
    "at": "2026-11-15T00:00:00.000Z"
  },
  "billingOwnsStatus": true
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	The organization ID 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 platform staff read an organization's escalation.	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, authentication_required, api_key_invalid, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Query parameters#

Response#

Examples#

Restricted and held there until a bank transfer arrives#

Errors#