# Close an organization

URL: https://heaven.dev/docs/reference/organizations/delete
Updated: 2026-11-21

Close an organization as its billing owner. Closure removes members, deletes Computers, pools and files, releases purchases and addresses, and refunds eligible unspent balance. Closure starts immediately if you are the only member. Otherwise, members get seven days' notice and you can cancel before closure starts.

`POST /v1/organization/delete`

## Parameters

- `dry_run` (boolean): Preview the change without applying it.
- `cancel` (boolean): Cancel the scheduled closure and keep the organization.
- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.

## Returns

- `data` (object, always present): The organization's closure state after scheduling, completing or canceling closure. A preview of the requested change.
  - `alternative-1` (object): The organization's closure state after scheduling, completing or canceling closure.
    - `closed` (boolean): Whether the organization closed immediately because no other members needed notice. May be omitted.
    - `closes_at` (string (date-time)): When scheduled closure takes effect. May be omitted.
    - `name` (string, always present): Organization name.
    - `unchanged` (boolean): True when cancellation found no scheduled closure to cancel. May be omitted.
  - `alternative-2` (object): A preview of the requested change.
    - `changes` (string[]): Proposed effects and losses. May be omitted.
    - `dry_run` (boolean, always present): True for a preview; no changes are made.
    - `message` (string, always present): What the request would do.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `payment_required` | 402 | Payment or credit is required. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- CLI: `heaven login` with `HEAVEN_API_KEY` unset. MCP: Heaven sign-in. cURL: `HEAVEN_SIGN_IN_KEY` from approved device sign-in (`POST /v1/auth/create`).
- A key limited to a command list cannot run this command.
- **Close:** Close the organization. Optional: `dry_run`, `organization`.
- **Cancel:** Cancel a scheduled organization closure. Required: `cancel`. Optional: `organization`.

## Examples

```sh tab="heaven CLI"
heaven organization delete
  [--dry-run]
  [--cancel]
  [--organization ORGANIZATION]
```

```sh tab="SSH"
ssh cli@heaven.dev organization delete
  [--dry-run]
  [--cancel]
  [--organization ORGANIZATION]
```

```sh tab="cURL"
curl https://heaven.dev/v1/organization/delete \
  -H "Authorization: Bearer $HEAVEN_SIGN_IN_KEY" \
  --json '{"organization": "acme"}'
```

```json tab="MCP"
{ "tool": "organization_delete",
  "arguments": { "organization": "acme" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "closed": true,
    "name": "acme"
  }
}
```
