Delete Sub-Account

Remove a client sub-account and stop billing its channels.

DELETE /api/webhooks/agency/:agency_key/sub-accounts/:ref
POST   /api/webhooks/agency/:agency_key/sub-accounts/:ref/delete

Both forms are identical. The POST alias exists for tools that cannot send DELETE.

Authentication

Requires a Bearer token with the sub_account.delete scope. See Agency Inbound API.

Path Parameters

Parameter	Type	Description
ref	string	Sub-account UUID, or ext:<external_ref>

Request Body

Field	Type	Required	Description
confirm	boolean	Yes	Must be true. Guards against an automation deleting your whole client base by mistake.

What happens

• Every active channel subscription is cancelled, so billing stops.
• Open charges for this sub-account are voided at the payment gateway. Your agency's monthly invoice is never touched.
• Users are deactivated and their emails are masked, which frees those addresses for reuse.
• external_ref is freed and can be assigned to a new sub-account.
• The data is kept for 90 days and then permanently purged. Within that window, an agency admin can restore the sub-account from the panel.

Response

{
  "ok": true,
  "event_id": "9e83c1e2-7b1c-4a44-8f2e-6c5a1b0d3f7b",
  "data": {
    "id": "a1b2c3d4-5678-4e9f-a0b1-c2d3e4f5a6b7",
    "deleted": true,
    "removedUsers": 3,
    "voidedCharges": 1,
    "purgeAt": "2026-10-26T14:22:00Z",
    "purgeDays": 90
  }
}

Example

cURL

curl --request DELETE \
  --url "https://api.getraze.co/api/webhooks/agency/AGENCY_KEY/sub-accounts/ext:client-42" \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{ "confirm": true }'

JavaScript

const response = await fetch(
  `https://api.getraze.co/api/webhooks/agency/${agencyKey}/sub-accounts/ext:client-42`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID()
    },
    body: JSON.stringify({ confirm: true })
  }
);
const data = await response.json();

Python

import requests, uuid

response = requests.delete(
    f'https://api.getraze.co/api/webhooks/agency/{agency_key}/sub-accounts/ext:client-42',
    headers={
        'Authorization': f'Bearer {token}',
        'Idempotency-Key': str(uuid.uuid4())
    },
    json={'confirm': True}
)
data = response.json()

Errors

Status	Code	Description
400	CONFIRMATION_REQUIRED	"confirm": true was not sent
401	UNAUTHORIZED	Missing, unknown or revoked token
403	INVALID_SCOPE	Token lacks sub_account.delete
403	SUB_ACCOUNT_FORBIDDEN	The sub-account belongs to another agency
404	SUB_ACCOUNT_NOT_FOUND	No live sub-account for that reference