# Close the organization

> The organizations.close operation: POST /api/v1/organizations/{id}/close in the REST API and the organizations_close tool in the MCP server.

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.

## At a glance

- **REST:** `POST /api/v1/organizations/{id}/close`
- **MCP tool:** `organizations_close`
- **Operation ID:** `organizations.close`
- **Scope:** Organization
- **Permission:** `org: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 `org:admin` scope
- **Fresh sign-in:** In the console, a sign-in within the last 15 minutes
- **Since:** M12

## Request

### Path parameters

| Field | Type       | Description |
| ----- | ---------- | ----------- |
| `id`  | `org_…` ID |             |

### Body

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

| Field           | Type                             | Required | Description                                                                                             |
| --------------- | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `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       |                                                                                                         |
| `confirm`       | string                           | Yes      | The organization's slug, as confirmation.                                                               |

## Response

`200 OK` with a JSON object:

| Field                      | Type                                                            | Description                                                          |
| -------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------- |
| `object`                   | `"organization_closure"`                                        |                                                                      |
| `orgId`                    | `org_…` ID                                                      |                                                                      |
| `status`                   | string                                                          | The organization's status: `closing` while it closes, then `closed`. |
| `subscriptions`            | one of `period_end`, `immediate`                                |                                                                      |
| `reason`                   | string or null                                                  |                                                                      |
| `requestedAt`              | date-time                                                       |                                                                      |
| `requestedBy`              | object                                                          |                                                                      |
| `requestedBy.type`         | string                                                          |                                                                      |
| `requestedBy.id`           | string                                                          |                                                                      |
| `subscriptionsCancelledAt` | date-time or null                                               |                                                                      |
| `subscriptionsEndedAt`     | date-time or null                                               |                                                                      |
| `closedAt`                 | date-time or null                                               |                                                                      |
| `retainUntil`              | date-time or null                                               | Financial records are kept until then, then deleted.                 |
| `blockers`                 | array of object                                                 | What still holds the closure (counted at most to 1,000).             |
| `blockers[].blocker`       | one of `subscriptions`, `invoices`, `refunds`, `filing_periods` |                                                                      |
| `blockers[].count`         | integer                                                         |                                                                      |

## Examples

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

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

{
  "subscriptions": "period_end",
  "reason": "We're winding the company down.",
  "confirm": "acme"
}
```

Response (`200`):

```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": []
}
```

## Errors

| Code                                                                                                   | HTTP status | When                                                                         | What to do                                                                                             |
| ------------------------------------------------------------------------------------------------------ | ----------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [`confirmation_mismatch`](https://ownrecord.io/docs/reference/errors.md#confirmation_mismatch)         | 400         | `confirm` isn't the organization's slug.                                     | Type exactly what the form asks for (the organization's slug, or your email address).                  |
| [`owner_required`](https://ownrecord.io/docs/reference/errors.md#owner_required)                       | 403         | You aren't an owner of the organization.                                     | Ask an organization owner (`org_owner`).                                                               |
| [`organization_not_closable`](https://ownrecord.io/docs/reference/errors.md#organization_not_closable) | 409         | The organization is suspended, closing or closed already (`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         | The ID isn't the organization of the request.                                | 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.                                                           |
| [`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, then repeat the action within 15 minutes.                                               |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)                 | 403         | You can't manage this organization.                                          | 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), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).