Excluir Sub-Conta

Remove uma sub-conta de cliente e para a cobranca dos canais dela.

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

As duas formas sao identicas. O atalho POST existe para ferramentas que nao conseguem enviar DELETE.

Autenticacao

Requer token Bearer com o escopo sub_account.delete. Veja API de Entrada da Agencia.

Parametros de Caminho

Parametro	Tipo	Descricao
ref	string	UUID da sub-conta, ou ext:<external_ref>

Corpo da Requisicao

Campo	Tipo	Obrigatorio	Descricao
confirm	boolean	Sim	Precisa ser true. Protege contra uma automacao excluir toda a sua carteira por engano.

O que acontece

• Toda assinatura de canal ativa e cancelada, entao a cobranca para.
• Cobrancas em aberto desta sub-conta sao anuladas no gateway de pagamento. A fatura mensal da sua agencia nunca e tocada.
• Os usuarios sao desativados e os e-mails mascarados, o que libera esses enderecos para reuso.
• O external_ref e liberado e pode ser atribuido a uma sub-conta nova.
• Os dados ficam guardados por 90 dias e depois sao apagados definitivamente. Dentro dessa janela, um admin da agencia pode restaurar a sub-conta pelo painel.

Resposta

{
  "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
  }
}

Exemplo

cURL

curl --request DELETE \
  --url "https://api.getraze.co/api/webhooks/agency/AGENCY_KEY/sub-accounts/ext:cliente-42" \
  --header "Authorization: Bearer SEU_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:cliente-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:cliente-42',
    headers={
        'Authorization': f'Bearer {token}',
        'Idempotency-Key': str(uuid.uuid4())
    },
    json={'confirm': True}
)
data = response.json()

Erros

Status	Codigo	Descricao
400	CONFIRMATION_REQUIRED	"confirm": true nao foi enviado
401	UNAUTHORIZED	Token ausente, desconhecido ou revogado
403	INVALID_SCOPE	O token nao tem sub_account.delete
403	SUB_ACCOUNT_FORBIDDEN	A sub-conta pertence a outra agencia
404	SUB_ACCOUNT_NOT_FOUND	Nenhuma sub-conta viva para essa referencia