# POST /v1/organizations/:orgId/suspend (/docs/api/reference/organizations/suspend-organization)



<Endpoint method="POST" path="/v1/organizations/:orgId/suspend" auth="Bearer" scope="org:admin" phase="1" />

Suspend a child organization — the per-customer kill switch. While suspended, the child's **own** API keys get `503 KILL_SWITCH` on every request: no generation, no credit spend, no webhook deliveries. Scheduled work holds. It's fully reversible with [resume](/docs/api/reference/organizations/resume-organization).

Your parent key can still read and manage a suspended child (that's how you resume or archive it) — only the child's own keys are cut off.

<Callout type="info">
  Idempotent by state: suspending an already-suspended org is a no-op that returns its current state. You cannot suspend an `archived` org (`409 CONFLICT`).
</Callout>

<Parameters
  title="Path"
  rows="[
  { name: 'orgId', type: 'string', required: true, description: 'The child org id (`org_`-prefixed or bare UUID).' },
]"
/>

## Example request [#example-request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80/suspend \
      -H "Authorization: Bearer $PARENT_KEY"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    const org = await fetch(
      "https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80/suspend",
      { method: "POST", headers: { "Authorization": `Bearer ${process.env.PARENT_KEY}` } },
    ).then((r) => r.json());
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import os, requests

    org = requests.post(
        "https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80/suspend",
        headers={"Authorization": f"Bearer {os.environ['PARENT_KEY']}"},
    ).json()
    ```
  </Tab>
</Tabs>

## Response [#response]

<Response status="200" description="OK">
  ```json
  {
    "id": "org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80",
    "parentOrganizationId": "org_2481fa5c-a404-44ed-a561-565392499abc",
    "name": "Acme Coffee",
    "status": "suspended",
    "metadata": { "externalId": "cust_12345", "plan": "growth" },
    "billingEmail": "ops@acme.example",
    "archivedAt": null,
    "createdAt": "2026-06-01T14:30:00.000000+00:00",
    "updatedAt": "2026-06-02T11:00:00.000000+00:00"
  }
  ```
</Response>

## Errors [#errors]

| Status | Code              | When                                                               |
| ------ | ----------------- | ------------------------------------------------------------------ |
| 404    | `NOT_FOUND`       | No such org, or it isn't a direct child of your org.               |
| 422    | `VALIDATION`      | The `:orgId` is not a valid organization id (malformed UUID).      |
| 409    | `CONFLICT`        | The org is `archived` — a terminal state that cannot be suspended. |
| 401    | `UNAUTHENTICATED` | Missing or invalid key.                                            |
| 403    | `FORBIDDEN_SCOPE` | Key lacks `org:admin`.                                             |

## See also [#see-also]

* [`POST /v1/organizations/:orgId/resume`](/docs/api/reference/organizations/resume-organization) — lift the suspension.
* [`DELETE /v1/organizations/:orgId`](/docs/api/reference/organizations/archive-organization) — permanently offboard.
* [Organizations concept](/docs/api/concepts/organizations) — the lifecycle diagram.