> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lista de bloqueio de clientes

> Bloqueie um cliente para impedir novos checkouts, cancelar suas assinaturas ativas e tornar seu Customer Portal somente leitura. Gerencie a lista de bloqueio em Settings ou pela API.

O bloqueio de clientes impede que um infrator conhecido compre de você novamente. Um cliente bloqueado não pode pagar, perde suas assinaturas ativas e pode visualizar sua conta no [Customer Portal](https://docs.dodopayments.com/features/customer-portal.md), mas não pode alterar suas assinaturas. Gerencie a lista de bloqueio em **Settings → Blocklist** ou pela Blocklist API.

![Página de configurações da lista de bloqueio mostrando o número total de clientes bloqueados, uma tabela de entradas bloqueadas com colunas de identificador, bloqueado por e bloqueado em, e um botão Add to Blocklist](https://mintcdn.com/dodopayments/c1t35qHSH45TR4GO/images/blocklist/blocklist-settings.png?fit=max\&auto=format\&n=c1t35qHSH45TR4GO\&q=85\&s=771eb4a5654fbd22e6a5110cfb1a2e9d)

The Blocklist tab under Settings

## O que acontece quando você bloqueia um cliente

O bloqueio entra em vigor assim que você o adiciona, em cada uma destas áreas:

| Área | Efeito |
| - | - |
| **Checkout** | Todas as tentativas de pagamento do email bloqueado são recusadas: payment links, checkout sessions e pagamentos ou assinaturas criados pela API. |
| **Assinaturas ativas** | Assinaturas com status `pending`, `active`, `on_hold` ou `paused` são canceladas com o motivo `cancelled_by_merchant`. O webhook `subscription.cancelled` usual é acionado para cada uma. |
| **Renovações e tentativas novamente** | As renovações automáticas e as [tentativas de pagamento novamente](https://docs.dodopayments.com/features/recovery/payment-retries.md) ignoram um cliente bloqueado, portanto nenhuma cobrança adicional é feita, mesmo que um cancelamento ainda esteja pendente. |
| **Nova tentativa manual** | Uma [nova tentativa manual](https://docs.dodopayments.com/features/recovery/manual-retry.md) do pagamento de um cliente bloqueado é recusada. |
| **Customer Portal** | O cliente ainda pode fazer login e visualizar faturas, assinaturas e chaves de licença. Ele não pode cancelar, pausar ou retomar uma assinatura, alterar planos, atualizar um método de pagamento ou editar o endereço da fatura. Ele ainda pode remover um método de pagamento salvo. |

> [!NOTE]
>
> O bloqueio não reembolsa pagamentos anteriores e não afeta disputas abertas. Emita qualquer reembolso separadamente na página [Refunds](https://docs.dodopayments.com/features/transactions/refunds.md).

## Como o bloqueio identifica os clientes

Você pode bloquear por **customer ID** ou por **email**. Em ambos os casos, o bloqueio usa o email do cliente, não o registro do cliente:

* **Todos os registros com esse email são abrangidos.** O Checkout pode criar um novo registro de cliente para um email recorrente, portanto um bloqueio baseado em um único customer ID poderia ser contornado. Um bloqueio baseado no email não pode.
* **Os aliases são abrangidos.** Os emails são comparados em letras minúsculas, com qualquer `+alias` removido, portanto `buyer+promo@example.com` e `Buyer@example.com` são considerados o mesmo cliente. Os pontos no endereço são mantidos como estão.
* **Limitado à sua empresa.** Um bloqueio se aplica apenas à sua empresa. O mesmo email ainda pode comprar de outras empresas no Dodo Payments.
* **O email deve pertencer a um cliente existente.** Você não pode bloquear um email que não corresponda a nenhum dos seus clientes, nem pode bloquear um registro de cliente sem email.

## Bloqueando um cliente

Você pode bloquear um cliente pela página Blocklist ou pela própria página do cliente.

**From Settings**

**1. Open the Blocklist**

Acesse **Settings → Blocklist** no seu dashboard.

**2. Add to Blocklist**

Clique em **Add to Blocklist** e insira o email ou o customer ID do cliente em **Customer ID or email**. O painel mostra o cliente correspondente.

**3. Confirm**

Clique em **Add to Blocklist** no painel. As assinaturas ativas do cliente são canceladas imediatamente, e a entrada aparece na tabela **Blocked entries**. Se algumas assinaturas ainda estiverem sendo canceladas, o dashboard exibirá um aviso. Atualize a página depois de alguns instantes para verificar.

**From the customer's page**

**1. Open the Customer**

Acesse **Sales → Customers** e abra o cliente que deseja bloquear.

**2. Block the Customer**

Abra o menu pelo ícone de três pontos e selecione **Block this Customer**.

**3. Confirm**

Clique em **Block**. Quando o bloqueio entrar em vigor, a página exibirá um selo **Blocked** ao lado do nome do cliente.

O dashboard não solicita um motivo. Para registrar por que você bloqueou o cliente, adicione uma nota na página do cliente ou envie `reason` ao bloquear pela API.

## Gerenciando clientes bloqueados

A página **Blocklist** lista todos os bloqueios ativos:

* **Total Customers Blocked**: Quantos clientes estão bloqueados no momento.
* **Blocked entries**: Uma linha por bloqueio, com o **Identifier** inserido (email ou customer ID), **Blocked By** e **Blocked On**. **Blocked By** mostra o membro da equipe que adicionou o bloqueio ou **API** para um bloqueio adicionado com uma API key.
* **Search Identifier** e **Filters**: Encontre uma entrada por email ou customer ID, ou filtre por **Blocked By** e **Blocked Between**.
* **Action**: **See Details** abre a página do cliente bloqueado, e **Unblock** remove o bloqueio. Membros da equipe com a função **Viewer** não podem desbloquear.

### Página do cliente bloqueado

![Customer Information page for a blocked customer showing the Blocked badge, an Unblock Customer button, an Activity Log with a note and the Added to blocklist event, and a Reference IDs panel with the customer ID](https://mintcdn.com/dodopayments/c1t35qHSH45TR4GO/images/blocklist/blocked-customer-details.png?fit=max\&auto=format\&n=c1t35qHSH45TR4GO\&q=85\&s=83e1225a8e71c003d2bf660f0eea9c08)

A blocked customer's details page

Abra um cliente bloqueado em **Sales → Customers** ou pela página Blocklist para ver:

* Um selo **Blocked** ao lado do nome do cliente e um botão **Unblock Customer**.
* **Activity Log**: Quando o cliente foi adicionado à lista de bloqueio, o motivo e quaisquer notas adicionadas pela sua equipe desde então. Clique em **Add Note** para registrar um novo contexto, como o resultado de um chargeback. Você pode editar uma nota posteriormente pela API.
* **Reference IDs**: O customer ID vinculado a este bloqueio, pronto para ser copiado.

## Desbloqueando um cliente

Para desbloquear um cliente, clique em **Unblock Customer** na página do cliente ou selecione **Unblock** na coluna **Action** da página Blocklist. Em seguida, confirme com **Unblock**.

* As alterações no Checkout e no Customer Portal são restauradas imediatamente.
* **Assinaturas canceladas não são reativadas.** O cliente precisa fazer uma nova compra.
* A entrada é mantida como registro de auditoria junto com suas notas, mas não aparece mais na lista de ativos.
* Você pode bloquear o mesmo cliente novamente mais tarde. Isso cria uma nova entrada.

## O que o cliente vê

Um cliente bloqueado nunca é informado de que foi bloqueado.

* **No Checkout**, o pagamento falha com uma recusa genérica: "This payment cannot be processed." A API retorna HTTP `403` com o código de erro `PAYMENT_NOT_PERMITTED`, que não informa nenhuma causa. O motivo real é registrado apenas nos logs do Dodo Payments.
* **No Customer Portal**, tudo fica visível, mas toda ação que altera a conta é recusada. Uma ação recusada retorna HTTP `403` com `PORTAL_ACTION_NOT_PERMITTED` e a mensagem "This action is not available." O perfil do portal contém `read_only: true`, portanto uma integração personalizada do portal pode desativar seus próprios controles. O portal nunca expõe a entrada da lista de bloqueio nem suas notas.

> [!WARNING]
>
> Se você exibe erros do Checkout ou do portal no seu próprio produto, mantenha este comportamento. Mostre uma mensagem genérica para `PAYMENT_NOT_PERMITTED` e `PORTAL_ACTION_NOT_PERMITTED`. Revelar o bloqueio informa ao infrator que ele deve tentar usar outro email.

## Usando a API

A Blocklist API permite bloquear clientes pelas suas próprias ferramentas, por exemplo quando chega um chargeback. Ela exige sua [API key](https://docs.dodopayments.com/api-reference/introduction.md) secreta. Qualquer key pode listar entradas e ler notas. Uma key com **write access** habilitado pode bloquear, desbloquear e gerenciar notas. O dashboard aplica a mesma divisão às funções da equipe: a função **Viewer** lê a lista, e a função **Editor** faz alterações.

A Blocklist API tem seis endpoints:

| Método | Endpoint | Finalidade |
| - | - | - |
| `GET` | `/blocklist/customers` | Lista clientes bloqueados, com filtros e uma contagem `total` |
| `POST` | `/blocklist/customers` | Bloqueia um cliente por customer ID ou email |
| `GET` | `/blocklist/customers/{entry_id}` | Obtém uma entrada junto com suas notas |
| `DELETE` | `/blocklist/customers/{entry_id}` | Desbloqueia um cliente |
| `POST` | `/blocklist/customers/{entry_id}/notes` | Adiciona uma nota |
| `PATCH` | `/blocklist/customers/{entry_id}/notes/{note_id}` | Atualiza uma nota |

A lista retorna apenas bloqueios ativos. Para filtrá-la, envie `identifier` (uma correspondência parcial e que não diferencia maiúsculas de minúsculas no email ou customer ID), `blocked_by_email`, `created_at_gte` ou `created_at_lte`. Por padrão, ela retorna 10 entradas por página: defina `page_size` para retornar até 100 e `page_number` para navegar entre as páginas.

### Bloquear um cliente

Envie `customer_id` ou `email` no nível superior do body. Se você enviar ambos, o bloqueio usará `customer_id`. `reason` é opcional e aparece na página da entrada. Um novo bloqueio retorna HTTP `201`.

```typescript Node.js expandable theme={null}
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
});

// Block by customer ID
const entry = await client.blocklist.customers.create({
  customer_id: 'cus_0NmichXWP8JYBB9Dw1Unj',
  reason: 'Chargeback on pay_0NmichXuYoNoapmr',
});

// Or block by email
const byEmail = await client.blocklist.customers.create({
  email: 'buyer@example.com',
  reason: 'Repeated refund abuse',
});

console.log(entry.id, entry.cancelled_subscription_ids);
```

```python Python expandable theme={null}
import os
from dodopayments import DodoPayments

client = DodoPayments(bearer_token=os.environ["DODO_PAYMENTS_API_KEY"])

# Block by customer ID
entry = client.blocklist.customers.create(
    customer_id="cus_0NmichXWP8JYBB9Dw1Unj",
    reason="Chargeback on pay_0NmichXuYoNoapmr",
)

# Or block by email
by_email = client.blocklist.customers.create(
    email="buyer@example.com",
    reason="Repeated refund abuse",
)

print(entry.id, entry.cancelled_subscription_ids)
```

```bash cURL theme={null}
curl -X POST https://live.dodopayments.com/blocklist/customers \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_0NmichXWP8JYBB9Dw1Unj",
    "reason": "Chargeback on pay_0NmichXuYoNoapmr"
  }'
```

A resposta descreve a entrada e as assinaturas que a chamada cancelou:

```json Response theme={null}
{
  "id": "bcu_7Hq2mV9kRt4LxYw3Pz",
  "customer_id": "cus_0NmichXWP8JYBB9Dw1Unj",
  "customer_name": "wow guy",
  "customer_email": "wowguy@example.com",
  "identifier": "cus_0NmichXWP8JYBB9Dw1Unj",
  "reason": "Chargeback on pay_0NmichXuYoNoapmr",
  "source": "api",
  "blocked_by_email": null,
  "created_at": "2026-09-02T12:09:41Z",
  "unblocked_at": null,
  "cancelled_subscription_ids": ["sub_3Fk8pW2nQs6MzXc1"],
  "subscriptions_swept": true
}
```

Estes campos exigem mais atenção:

| Campo | Descrição |
| - | - |
| `identifier` | O customer ID ou email enviado. |
| `source` | De onde veio o bloqueio: `blocklist_page`, `customer_page`, `payment_page`, `dispute_page` ou `api`. Uma API key sempre registra `api`, independentemente do `source` enviado. |
| `blocked_by_email` | O usuário do dashboard que adicionou o bloqueio. `null` para uma API key. |
| `cancelled_subscription_ids` | Assinaturas canceladas por esta chamada. Presente somente na resposta de criação. |
| `remaining_subscription_ids` | Assinaturas ainda ativas porque um cancelamento falhou ou a chamada atingiu seu limite de 25 cancelamentos. |
| `subscriptions_swept` | `false` quando ainda houver assinaturas ativas ou quando o Dodo Payments não conseguir listá-las. Repita a chamada até que o valor seja `true`. O bloqueio em si já está em vigor. |

> [!NOTE]
>
> Bloquear um cliente que já está bloqueado retorna HTTP `409` com `CUSTOMER_ALREADY_BLOCKED`, a menos que ainda existam assinaturas aguardando cancelamento. Nesse caso, a chamada continua o cancelamento e retorna HTTP `200`.

### Verificando se um cliente está bloqueado

[Get Customer Detail](https://docs.dodopayments.com/api-reference/customers/get-customers-1.md) retorna dois campos adicionais: `blocked_at`, o momento em que o bloqueio ativo foi adicionado (`null` quando o cliente não está bloqueado), e `blocklist_entry_id`, a entrada relacionada. O endpoint [List Customers](https://docs.dodopayments.com/api-reference/customers/get-customers.md) deixa ambos vazios.

### Desbloqueando um cliente

```typescript Node.js theme={null}
await client.blocklist.customers.delete('bcu_7Hq2mV9kRt4LxYw3Pz');
```

```python Python theme={null}
client.blocklist.customers.delete("bcu_7Hq2mV9kRt4LxYw3Pz")
```

```bash cURL theme={null}
curl -X DELETE https://live.dodopayments.com/blocklist/customers/bcu_7Hq2mV9kRt4LxYw3Pz \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"
```

O endpoint retorna HTTP `204` em caso de sucesso e HTTP `404` quando o ID não corresponde a nenhum bloqueio ativo. O desbloqueio restaura as operações de escrita no Checkout e no portal, mas não reativa nenhuma assinatura.

## Práticas recomendadas

* **Registre o motivo.** Um motivo curto no bloqueio, junto com notas sobre o que acontecer depois, fornece à sua equipe de suporte o contexto completo sem sair do dashboard.
* **Bloqueie após um chargeback.** Abra a página do cliente pela disputa ou pelo pagamento e bloqueie-o ali, ou automatize o processo pelo webhook `dispute.opened` com `POST /blocklist/customers`. Consulte [Disputes](https://docs.dodopayments.com/features/transactions/disputes.md).
* **Verifique `subscriptions_swept`.** Ao bloquear pela API, repita a chamada até que a resposta informe `true`, para que nenhuma assinatura ativa permaneça.
* **Reembolse separadamente.** Um bloqueio interrompe apenas compras futuras. Se você deve dinheiro ao cliente, reembolse o pagamento normalmente.
* **Revise a lista.** Desbloqueie clientes cujo problema foi resolvido. O desbloqueio é imediato e mantém o histórico.

## Relacionado

> **[Customer Management](https://docs.dodopayments.com/features/customers.md)**
>
> Encontre um cliente, abra a página de detalhes e gerencie suas assinaturas.

> **[Customer Portal](https://docs.dodopayments.com/features/customer-portal.md)**
>
> O que um cliente bloqueado pode e não pode fazer no portal.

> **[Disputes](https://docs.dodopayments.com/features/transactions/disputes.md)**
>
> Responda a chargebacks e decida quando um bloqueio é necessário.

> **[Error Codes](https://docs.dodopayments.com/api-reference/error-codes.md)**
>
> O que `PAYMENT_NOT_PERMITTED` e `PORTAL_ACTION_NOT_PERMITTED` significam.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.