POST /v1/organizations/:orgId/suspend
Surgically disable one customer org — the per-child kill switch.
POST
/v1/organizations/:orgId/suspendPhase 1stableidempotent
- Auth
- Bearer
- Scope
- org:admin
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.
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.
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).
Path
orgIdstringrequiredThe child org id (`org_`-prefixed or bare UUID).
Example request
curl -X POST https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80/suspend \
-H "Authorization: Bearer $PARENT_KEY"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());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()Response
200OK
{
"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"
}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
POST /v1/organizations/:orgId/resume— lift the suspension.DELETE /v1/organizations/:orgId— permanently offboard.- Organizations concept — the lifecycle diagram.