# Organizations tools

> MCP tools for Organizations: organizations_close, organizations_closure_get, organizations_create, organizations_export, organizations_exports_list, organizations_get, organizations_list_mine, organizations_reinstate, organizations_suspend, organizations_update.

- `organizations_close`: Close the organization
- `organizations_closure_get`: Get the organization's closure
- `organizations_create`: Create an organization
- `organizations_export`: Export the organization's data
- `organizations_exports_list`: List the organization's exports
- `organizations_get`: Get the organization
- `organizations_list_mine`: List your organizations
- `organizations_reinstate`: Lift an abuse suspension
- `organizations_suspend`: Suspend an organization for abuse
- `organizations_update`: Update the organization

## `organizations_close`

**Close the organization.** Operation [`organizations.close`](https://ownrecord.io/docs/reference/organizations-close.md) · Organization level · permission `org:admin` · risk tier `security` · since M12

Starts closing the organization. It becomes `closing` at once:

1. live brands stop taking new checkouts;
2. every subscription is cancelled the way you choose: at the end of its current period, or immediately (the
   customers are told);
3. the organization stays `closing` until its open invoices, refunds and final filing periods are done;
4. then it is `closed`: read-only, and you can still export its data (`organizations.export`).

Financial records are kept for the legal retention period (10 years by default, longer where an entity's
country requires it), then deleted. Personal data not needed for financial records is pseudonymised when the
organization closes. Closing can't be undone from the console.

Only an owner can close the organization, with a sign-in in the last 15 minutes, confirming with its slug.

Annotations: `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: false` · `openWorldHint: true`

### Arguments

| Argument          | Type                             | Required | Description                                                                                                                                                                                              |
| ----------------- | -------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`org_…`)                     | yes      | –                                                                                                                                                                                                        |
| `subscriptions`   | one of `period_end`, `immediate` | yes      | `period_end`: subscriptions end when their current period ends; `immediate`: they end now, with notice.                                                                                                  |
| `reason`          | string                           | no       | (at most 1000 characters)                                                                                                                                                                                |
| `confirm`         | string                           | yes      | The organization's slug, as confirmation. (1–64 characters)                                                                                                                                              |
| `idempotency_key` | string                           | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean                          | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`confirmation_mismatch`](https://ownrecord.io/docs/reference/errors.md#confirmation_mismatch): `confirm` isn't the organization's slug.
- [`owner_required`](https://ownrecord.io/docs/reference/errors.md#owner_required): You aren't an owner of the organization.
- [`organization_not_closable`](https://ownrecord.io/docs/reference/errors.md#organization_not_closable): The organization is suspended, closing or closed already (`details.status`).
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The ID isn't the organization of the request.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The organization changed at the same time; retry.
- [`fresh_auth_required`](https://ownrecord.io/docs/reference/errors.md#fresh_auth_required): Your last sign-in is older than 15 minutes.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't manage this organization.

### Example

**Close, letting subscriptions run to the end of their period**

Arguments:

```json
{
  "id": "org_01m4tx5nj7ekd958x53w4bntcg",
  "subscriptions": "period_end",
  "reason": "We're winding the company down.",
  "confirm": "acme",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "object": "organization_closure",
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "status": "closing",
  "subscriptions": "period_end",
  "reason": "We're winding the company down.",
  "requestedAt": "2026-10-26T09:00:00.000Z",
  "requestedBy": {
    "type": "user",
    "id": "usr_01m4tx5nj8emwbyf7y9vcf47xa"
  },
  "subscriptionsCancelledAt": null,
  "subscriptionsEndedAt": null,
  "closedAt": null,
  "retainUntil": null,
  "blockers": []
}
```

## `organizations_closure_get`

**Get the organization's closure.** Operation [`organizations.closure.get`](https://ownrecord.io/docs/reference/organizations-closure-get.md) · Organization level · permission `org:read` · risk tier `read` · since M12

Returns the organization's status and, once closing started, the closure: how subscriptions end, when they were
cancelled and ended, what still holds the closure (`blockers`: subscriptions not ended yet, open invoices,
pending refunds, final filing periods not submitted), when it closed and until when its financial records are
kept. `closure` is null for an organization that isn't closing.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument | Type         | Required | Description |
| -------- | ------------ | -------- | ----------- |
| `id`     | ID (`org_…`) | yes      | –           |

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The ID isn't the organization of the request.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't read this organization.

### Example

**Closing, subscriptions still running**

Arguments:

```json
{
  "id": "org_01m4tx5nj7ekd958x53w4bntcg"
}
```

Result `output`:

```json
{
  "object": "organization_closure_status",
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "status": "closing",
  "closure": {
    "object": "organization_closure",
    "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
    "status": "closing",
    "subscriptions": "period_end",
    "reason": "We're winding the company down.",
    "requestedAt": "2026-10-26T09:00:00.000Z",
    "requestedBy": {
      "type": "user",
      "id": "usr_01m4tx5nj8emwbyf7y9vcf47xa"
    },
    "subscriptionsCancelledAt": null,
    "subscriptionsEndedAt": null,
    "closedAt": null,
    "retainUntil": null,
    "blockers": [
      {
        "blocker": "subscriptions",
        "count": 12
      }
    ]
  }
}
```

## `organizations_create`

**Create an organization.** Operation [`organizations.create`](https://ownrecord.io/docs/reference/organizations-create.md) · Platform level · permission `account:write` · risk tier `write` · since M1

Creates an organization (the account and the boundary for all its data) and makes you its owner
(`org_owner`). The slug appears in console URLs (`/console/{slug}`) and is unique across Ownrecord:
3 to 40 lowercase letters, digits and single hyphens.

**Who can call it:** any signed-in user, from the console. API keys belong to an organization, so they
can't create one.

New organizations start on Ownrecord's free `sandbox` plan (test mode only): Ownrecord creates the
organization's billing account and subscription right after. Upgrade in Organization → Billing
(`platform_billing.change_plan`) to take live payments. Add a legal entity next, then a brand.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: false` · `openWorldHint: false`

### Arguments

| Argument          | Type    | Required | Description                                                                                                                                                                                              |
| ----------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | string  | yes      | (1–120 characters)                                                                                                                                                                                       |
| `slug`            | string  | yes      | (3–40 characters)                                                                                                                                                                                        |
| `country`         | string  | yes      | –                                                                                                                                                                                                        |
| `idempotency_key` | string  | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): The name, slug or country is missing or malformed.
- [`slug_invalid`](https://ownrecord.io/docs/reference/errors.md#slug_invalid): The slug has the wrong format or is a reserved word such as `api`.
- [`slug_taken`](https://ownrecord.io/docs/reference/errors.md#slug_taken): Another organization already uses this slug.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): The caller isn't a signed-in user (for example, an API key).

### Example

**Create an organization**

Arguments:

```json
{
  "name": "Acme",
  "slug": "acme",
  "country": "HR",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "org_01m4tx5nj7ekd958x53w4bntcg",
  "object": "organization",
  "slug": "acme",
  "name": "Acme",
  "country": "HR",
  "status": "active",
  "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"
}
```

## `organizations_export`

**Export the organization's data.** Operation [`organizations.export`](https://ownrecord.io/docs/reference/organizations-export.md) · Organization level · permission `org:admin` · risk tier `security` · since M12

Requests an export of everything in the organization: one JSON file per kind of record (legal entities,
brands, customers, subscriptions, invoices, the ledger, registrations, filings and the rest, both modes), plus
the PDFs of its invoices and credit notes, in one ZIP archive. Secrets, hashes and tokens are left out.

It's built in the background (poll `organizations.exports.list` until `status` is `ready`) and can be
downloaded from the console for 7 days. One export is built at a time. Closed organizations can still export.

Needs `org:admin` (organization owners and admins). Security tier for agents: it holds all of the
organization's data.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: false` · `openWorldHint: false`

### Arguments

| Argument          | Type         | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`org_…`) | yes      | –                                                                                                                                                                                                        |
| `idempotency_key` | string       | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean      | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`organization_export_in_progress`](https://ownrecord.io/docs/reference/errors.md#organization_export_in_progress): An export is already queued or being built.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The ID isn't the organization of the request.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't export this organization.

### Example

**Request an export**

Arguments:

```json
{
  "id": "org_01m4tx5nj7ekd958x53w4bntcg",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "exp_01m4tx5nj8emwbyf7y9vcf47xf",
  "object": "organization_export",
  "status": "queued",
  "requestedBy": {
    "type": "user",
    "id": "usr_01m4tx5nj8emwbyf7y9vcf47xa"
  },
  "file": null,
  "failure": null,
  "readyAt": null,
  "expiresAt": null,
  "createdAt": "2026-10-26T09:00:00.000Z",
  "updatedAt": "2026-10-26T09:00:00.000Z"
}
```

## `organizations_exports_list`

**List the organization's exports.** Operation [`organizations.exports.list`](https://ownrecord.io/docs/reference/organizations-exports-list.md) · Organization level · permission `org:admin` · risk tier `read` · since M12

Lists the organization's data exports, newest first (at most 20): `queued`, `running`, `ready` with the archive
(downloadable from the console for 7 days, then `expired`) or `failed` with the reason.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument | Type         | Required | Description |
| -------- | ------------ | -------- | ----------- |
| `id`     | ID (`org_…`) | yes      | –           |

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The ID isn't the organization of the request.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't export this organization.

### Example

**A ready export**

Arguments:

```json
{
  "id": "org_01m4tx5nj7ekd958x53w4bntcg"
}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "exp_01m4tx5nj8emwbyf7y9vcf47xf",
      "object": "organization_export",
      "status": "ready",
      "requestedBy": {
        "type": "user",
        "id": "usr_01m4tx5nj8emwbyf7y9vcf47xa"
      },
      "file": {
        "fileId": "file_01m4tx5nj8emwbyf7y9vcf47xg",
        "filename": "ownrecord-export-2026-10-26.zip",
        "contentType": "application/zip",
        "size": 482113,
        "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
        "documents": 1204
      },
      "failure": null,
      "readyAt": "2026-10-26T09:00:00.000Z",
      "expiresAt": "2026-11-02T09:00:00.000Z",
      "createdAt": "2026-10-26T09:00:00.000Z",
      "updatedAt": "2026-10-26T09:00:00.000Z"
    }
  ]
}
```

## `organizations_get`

**Get the organization.** Operation [`organizations.get`](https://ownrecord.io/docs/reference/organizations-get.md) · Organization level · permission `org:read` · risk tier `read` · since M1

Returns the organization of the request: name, slug, country, status, support-access policy and its
effective plan entitlements (`entitlements`: the plan's values with any active override applied), which
decide limits such as `entities.max` and `brands.max`.

`id` must be the organization the credentials belong to; any other ID is `resource_not_found`. Readable by
organization-level members and org management keys.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument | Type         | Required | Description |
| -------- | ------------ | -------- | ----------- |
| `id`     | ID (`org_…`) | yes      | –           |

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The ID isn't the organization of the request.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't read this organization's settings.

### Example

**Read the organization**

Arguments:

```json
{
  "id": "org_01m4tx5nj7ekd958x53w4bntcg"
}
```

Result `output`:

```json
{
  "id": "org_01m4tx5nj7ekd958x53w4bntcg",
  "object": "organization",
  "slug": "acme",
  "name": "Acme",
  "country": "HR",
  "status": "active",
  "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"
}
```

## `organizations_list_mine`

**List your organizations.** Operation [`organizations.list_mine`](https://ownrecord.io/docs/reference/organizations-list-mine.md) · Platform level · permission `account:read` · risk tier `read` · since M1

Lists the organizations you belong to, with each of your memberships there: the role, the scope (the
whole organization, one legal entity or one brand, with its slug and name) and whether it has live-mode
access. The console uses it for the organization switcher. Sorted by name; `limit` (1–100, default 100) and `starting_after` (an organization ID, the `next_cursor` of the previous page) paginate.

**Who can call it:** any signed-in user. API keys can't (a key belongs to one organization; use
`organizations.get`).

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument         | Type         | Required | Description |
| ---------------- | ------------ | -------- | ----------- |
| `limit`          | integer      | no       | (1–100)     |
| `starting_after` | ID (`org_…`) | no       | –           |

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): The caller isn't a signed-in user (for example, an API key).

### Example

**An owner of one organization and a developer on a brand of another**

Arguments:

```json
{}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "org_01m4tx5nj7ekd958x53w4bntcg",
      "object": "organization",
      "slug": "acme",
      "name": "Acme",
      "status": "active",
      "isPlatform": false,
      "memberships": [
        {
          "id": "mem_01m4tx5nj8emwbyf7y9vcf47x6",
          "role": "org_owner",
          "scope": {
            "type": "org"
          },
          "livemodeAccess": true
        }
      ]
    },
    {
      "id": "org_01m4tx5nj8emwbyf7y9vcf47x1",
      "object": "organization",
      "slug": "globex",
      "name": "Globex",
      "status": "active",
      "isPlatform": false,
      "memberships": [
        {
          "id": "mem_01m4tx5nj8emwbyf7y9vcf47x7",
          "role": "developer",
          "scope": {
            "type": "brand",
            "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x5",
            "brand": {
              "slug": "globex-cloud",
              "name": "Globex Cloud",
              "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x3",
              "entitySlug": "globex-us"
            }
          },
          "livemodeAccess": false
        }
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## `organizations_reinstate`

**Lift an abuse suspension.** Operation [`organizations.reinstate`](https://ownrecord.io/docs/reference/organizations-reinstate.md) · Platform level · permission `platform:admin` · risk tier `security` · since M12

Platform admins: lifts a suspension made for abuse or an AUP violation (`organizations.suspend`). The
organization's status is then what its Ownrecord subscription says: `active` when it is paid (also when it was
paid during the suspension), otherwise the stage that is due for how long it has been unpaid (restricted after
14 days, suspended after 30, by default). A suspension for non-payment isn't lifted here: it ends when the open
invoices are paid.

Security tier; audited.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: false` · `openWorldHint: false`

### Arguments

| Argument          | Type         | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orgId`           | ID (`org_…`) | yes      | –                                                                                                                                                                                                        |
| `idempotency_key` | string       | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean      | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`fresh_auth_required`](https://ownrecord.io/docs/reference/errors.md#fresh_auth_required): Your last sign-in is older than 15 minutes: sign in again first.
- [`organization_not_suspended`](https://ownrecord.io/docs/reference/errors.md#organization_not_suspended): The organization has no abuse suspension.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No such organization.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The organization changed at the same time; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You aren't a platform admin.

### Example

**Reinstate**

Arguments:

```json
{
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "org_01m4tx5nj7ekd958x53w4bntcg",
  "object": "organization",
  "slug": "acme",
  "name": "Acme",
  "country": "HR",
  "status": "active",
  "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"
}
```

## `organizations_suspend`

**Suspend an organization for abuse.** Operation [`organizations.suspend`](https://ownrecord.io/docs/reference/organizations-suspend.md) · Platform level · permission `platform:admin` · risk tier `security` · since M12

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.

Annotations: `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: false` · `openWorldHint: false`

### Arguments

| Argument          | Type                    | Required | Description                                                                                                                                                                                              |
| ----------------- | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orgId`           | ID (`org_…`)            | yes      | –                                                                                                                                                                                                        |
| `kind`            | one of `abuse`, `fraud` | yes      | –                                                                                                                                                                                                        |
| `reason`          | string                  | yes      | (1–1000 characters)                                                                                                                                                                                      |
| `idempotency_key` | string                  | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean                 | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`fresh_auth_required`](https://ownrecord.io/docs/reference/errors.md#fresh_auth_required): Your last sign-in is older than 15 minutes: sign in again first.
- [`organization_already_suspended`](https://ownrecord.io/docs/reference/errors.md#organization_already_suspended): The organization is suspended already.
- [`organization_not_closable`](https://ownrecord.io/docs/reference/errors.md#organization_not_closable): The organization is closing or closed (`details.status`).
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No such organization.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The organization changed at the same time; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You aren't a platform admin.

### Example

**Suspend for an AUP violation**

Arguments:

```json
{
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "kind": "abuse",
  "reason": "Sells counterfeit goods (AUP report #42).",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```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"
}
```

## `organizations_update`

**Update the organization.** Operation [`organizations.update`](https://ownrecord.io/docs/reference/organizations-update.md) · Organization level · permission `org:write` · risk tier `write` · since M1

Renames the organization or changes its slug. Organization slugs are unique across Ownrecord; a new slug
moves the console URLs (`/console/{slug}`), and old links stop working. API keys keep working.

Needs `org:write` (organization owners and admins).

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type         | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`org_…`) | yes      | –                                                                                                                                                                                                        |
| `name`            | string       | no       | (1–120 characters)                                                                                                                                                                                       |
| `slug`            | string       | no       | (3–40 characters)                                                                                                                                                                                        |
| `idempotency_key` | string       | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean      | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): Neither name nor slug was sent, or one is malformed.
- [`slug_invalid`](https://ownrecord.io/docs/reference/errors.md#slug_invalid): The slug has the wrong format or is a reserved word.
- [`slug_taken`](https://ownrecord.io/docs/reference/errors.md#slug_taken): Another organization already uses this slug.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The ID isn't the organization of the request.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The organization changed at the same time; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't change this organization's settings.

### Example

**Rename the organization**

Arguments:

```json
{
  "id": "org_01m4tx5nj7ekd958x53w4bntcg",
  "name": "Acme Group",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "org_01m4tx5nj7ekd958x53w4bntcg",
  "object": "organization",
  "slug": "acme",
  "name": "Acme Group",
  "country": "HR",
  "status": "active",
  "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-14T09:30:00.000Z"
}
```