# Suspend an organization for abuse

> The organizations.suspend operation: POST /api/v1/platform/organizations/{orgId}/suspend in the REST API and the organizations_suspend tool in the MCP server.

Platform admins: suspends an organization for abuse or a violation of the Acceptable Use Policy, with the
reason. A suspended organization takes no new live checkout sessions, but renewals of existing subscriptions,
refunds, the customer portal and filings continue, so its customers and tax authorities aren't left without
what they're owed. `kind: fraud` is recorded the same way; a fraud case then follows its runbook.
`organizations.reinstate` lifts the suspension.

Security tier; every suspension is audited.

## At a glance

- **REST:** `POST /api/v1/platform/organizations/{orgId}/suspend`
- **MCP tool:** `organizations_suspend`
- **Operation ID:** `organizations.suspend`
- **Scope:** Platform
- **Permission:** `platform:admin`
- **Risk tier:** `security`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` required
- **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 |             |

### Body

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

| Field    | Type                    | Required | Description |
| -------- | ----------------------- | -------- | ----------- |
| `kind`   | one of `abuse`, `fraud` | Yes      |             |
| `reason` | string                  | Yes      |             |

## Response

`200 OK` with a JSON object:

| Field           | Type                                                                  | Description |
| --------------- | --------------------------------------------------------------------- | ----------- |
| `id`            | `org_…` ID                                                            |             |
| `object`        | `"organization"`                                                      |             |
| `slug`          | string                                                                |             |
| `name`          | string                                                                |             |
| `country`       | string                                                                |             |
| `status`        | one of `active`, `restricted`, `suspended`, `closing`, `closed`       |             |
| `isPlatform`    | boolean                                                               |             |
| `supportAccess` | one of `off`, `on_request`, `always_read`                             |             |
| `requireMfa`    | boolean                                                               |             |
| `entitlements`  | object                                                                |             |
| `plan`          | object                                                                |             |
| `plan.status`   | one of `trialing`, `active`, `past_due`, `unpaid`, `canceled`, `none` |             |
| `plan.override` | object or null                                                        |             |
| `createdBy`     | `usr_…` ID                                                            |             |
| `createdAt`     | date-time                                                             |             |
| `updatedAt`     | date-time                                                             |             |

## Examples

### Suspend for an AUP violation

```http
POST /api/v1/platform/organizations/org_01m4tx5nj7ekd958x53w4bntcg/suspend
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "kind": "abuse",
  "reason": "Sells counterfeit goods (AUP report #42)."
}
```

Response (`200`):

```json
{
  "id": "org_01m4tx5nj7ekd958x53w4bntcg",
  "object": "organization",
  "slug": "acme",
  "name": "Acme",
  "country": "HR",
  "status": "suspended",
  "isPlatform": false,
  "supportAccess": "on_request",
  "requireMfa": false,
  "entitlements": {
    "livemode": true,
    "entities.max": 2,
    "brands.max": 3,
    "members.max": 10,
    "jurisdictions.registered.max": 10,
    "subscriptions.enabled": true,
    "usage_billing.enabled": true,
    "einvoicing.enabled": true,
    "processors.secondary": false,
    "custom_domains.max": 2,
    "api.rate_limit_rps": 100,
    "audit.retention_days": 90,
    "support.level": "email",
    "filing.reports": "full",
    "sso.enabled": false,
    "assistant.enabled": true,
    "assistant.messages_per_month": 1000
  },
  "plan": {
    "status": "none",
    "override": {
      "reason": "Temporary Growth entitlements until platform billing (M12)",
      "expiresAt": null
    }
  },
  "createdBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z"
}
```

## Errors

| Code                                                                                                             | HTTP status | When                                                             | What to do                                                                                             |
| ---------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [`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.                                               |
| [`organization_already_suspended`](https://ownrecord.io/docs/reference/errors.md#organization_already_suspended) | 409         | The organization is suspended already.                           | Nothing to do, or reinstate it first to change the reason.                                             |
| [`organization_not_closable`](https://ownrecord.io/docs/reference/errors.md#organization_not_closable)           | 409         | The organization is closing or closed (`details.status`).        | A suspended organization is closed with Ownrecord support; a closing or closed one needs nothing more. |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found)                         | 404         | No such organization.                                            | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.   |
| [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict)                             | 409         | The organization changed at the same time; retry.                | Fetch the object again and retry the change.                                                           |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)                           | 403         | You aren't a platform admin.                                     | Ask an organization owner or admin for a role or scope that allows this action.                        |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`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), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`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), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).