# DELETE /v1/organizations/:orgId (/docs/api/reference/organizations/archive-organization)



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

Offboard a customer in one call. Archiving a child org is **terminal**: its status moves to `archived`, all of its API keys are revoked, and it can never be restored. This is the clean cut the flat model can't give you — no lingering OAuth tokens, no entangled credit history.

<Callout type="warn">
  Archival is irreversible by design. If the same customer returns, create a fresh child org. An archived org cannot be resumed or re-activated.
</Callout>

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

<Parameters
  title="Headers"
  rows="[
  { name: 'Idempotency-Key', type: 'string (UUID)', description: 'Optional. Archiving an already-archived org is itself idempotent and returns its terminal state.' },
]"
/>

## Example request [#example-request]

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

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

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

    result = requests.delete(
        "https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80",
        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",
    "status": "archived",
    "archivedAt": "2026-06-02T13:00:00.000000+00:00",
    "reclaimedCredits": 3200,
    "revokedApiKeys": 2
  }
  ```
</Response>

### Field notes [#field-notes]

* `revokedApiKeys` is the number of the child's active keys that were revoked by this call.
* `reclaimedCredits` is the child's unspent **non-reserved** balance, swept back to the parent wallet as part of this call. Credits reserved for in-flight generations are not reclaimed. It's `0` only when the child had nothing reclaimable (never funded, or fully spent). See [allocate](/docs/api/reference/organizations/credits/allocate) for the funding side.

## 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). |
| 401    | `UNAUTHENTICATED` | Missing or invalid key.                                       |
| 403    | `FORBIDDEN_SCOPE` | Key lacks `org:admin`.                                        |

## See also [#see-also]

* [`POST /v1/organizations/:orgId/suspend`](/docs/api/reference/organizations/suspend-organization) — a reversible pause, if you're not ready to offboard.
* [Organizations concept](/docs/api/concepts/organizations) — the lifecycle diagram.