> ## 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.

<Info>
  A lista de bloqueio de clientes impede que um fraudador conhecido compre de você novamente. Um cliente bloqueado não pode pagar, perde suas assinaturas ativas e pode visualizar, mas não alterar nada no [Customer Portal](/features/customer-portal). Gerencie a lista em **Settings → Blocklist** ou pela API da lista de bloqueio.
</Info>

<Frame caption="The Blocklist tab under Settings">
  <img src="https://mintcdn.com/dodopayments/c1t35qHSH45TR4GO/images/blocklist/blocklist-settings.png?fit=max&auto=format&n=c1t35qHSH45TR4GO&q=85&s=771eb4a5654fbd22e6a5110cfb1a2e9d" alt="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" style={{ maxHeight: '500px', width: 'auto' }} width="2358" height="1554" data-path="images/blocklist/blocklist-settings.png" />
</Frame>

## O que acontece quando você bloqueia um cliente

| Área                                  | Efeito                                                                                                                                                                                                                                                   |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Checkout**                          | Toda tentativa de pagamento feita pelo email bloqueado é recusada: payment links, checkout sessions e payments ou subscriptions criados pela API.                                                                                                        |
| **Live subscriptions**                | As subscriptions nos status `pending`, `active`, `on_hold` ou `paused` são canceladas com o motivo `cancelled_by_merchant`. O webhook `subscription.cancelled` usual é disparado para cada uma.                                                          |
| **Renovações e tentativas novamente** | As renovações automáticas e as [tentativas novamente de pagamento](/features/recovery/payment-retries) ignoram um cliente bloqueado, portanto nenhuma cobrança adicional é feita, mesmo que um cancelamento ainda esteja pendente.                       |
| **Tentativa manual novamente**        | Uma [tentativa manual novamente](/features/recovery/manual-retry) do pagamento de um cliente bloqueado é recusada.                                                                                                                                       |
| **Customer Portal**                   | O cliente ainda pode fazer login e visualizar invoices, subscriptions e license keys, mas não pode cancelar, pausar ou retomar uma subscription, alterar planos ou atualizar um payment method. A remoção de um payment method salvo continua permitida. |

<Note>
  O bloqueio não reembolsa pagamentos anteriores nem afeta disputas abertas. Emita qualquer reembolso separadamente na página de [Refunds](/features/transactions/refunds).
</Note>

## Como o bloqueio identifica os clientes

Você pode bloquear por **customer ID** ou por **email**. De qualquer forma, o bloqueio é baseado no email do cliente, não no registro do cliente:

* **Todos os registros com esse email são abrangidos.** O Checkout pode criar um novo registro de cliente para um email que retorna, 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 ao seu negócio.** Um bloqueio se aplica somente ao seu negócio. O mesmo email ainda pode comprar de outros negócios no Dodo Payments.
* **O email deve pertencer a um cliente existente.** Você não pode bloquear um email que nunca tenha feito checkout com você, e um registro de cliente sem email não pode ser bloqueado.

## Bloqueando um cliente

<Tabs>
  <Tab title="From Settings">
    <Steps>
      <Step title="Open the Blocklist">
        Acesse **Settings → Blocklist** no dashboard.
      </Step>

      <Step title="Add to Blocklist">
        Clique em **Add to Blocklist** e insira o email ou customer ID do cliente. Adicione um motivo para que sua equipe possa ver posteriormente por que o bloqueio foi adicionado.
      </Step>

      <Step title="Confirm">
        Confirme o bloqueio. As live subscriptions do cliente são canceladas imediatamente, e a entrada aparece na tabela **Blocked entries**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="From the customer's page">
    <Steps>
      <Step title="Open the customer">
        Acesse **Sales → Customers** e abra o cliente que você deseja bloquear.
      </Step>

      <Step title="Block the customer">
        Clique em **Block Customer**. Quando o bloqueio estiver em vigor, a página exibirá um selo **Blocked** ao lado do nome do cliente.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Gerenciando clientes bloqueados

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

* **Total Customers Blocked**: Quantos clientes estão bloqueados atualmente.
* **Blocked entries**: Uma linha por bloqueio, com o **Identifier** inserido por você (email ou customer ID), **Blocked By** (o membro da equipe que adicionou o bloqueio) e **Blocked On**.
* **Search Identifier** e **Filters**: Encontre uma entrada por email ou customer ID, ou filtre por quem a bloqueou e quando.
* **Action**: Gerencie a entrada, incluindo desbloquear o cliente.

### A página do cliente bloqueado

<Frame caption="A blocked customer's details page">
  <img src="https://mintcdn.com/dodopayments/c1t35qHSH45TR4GO/images/blocklist/blocked-customer-details.png?fit=max&auto=format&n=c1t35qHSH45TR4GO&q=85&s=83e1225a8e71c003d2bf660f0eea9c08" alt="Página Customer Information de um cliente bloqueado mostrando o selo Blocked, um botão Unblock Customer, um Activity Log com uma observação e o evento Added to blocklist, e um painel Reference IDs com o customer ID" style={{ maxHeight: '500px', width: 'auto' }} width="2366" height="1554" data-path="images/blocklist/blocked-customer-details.png" />
</Frame>

Abra um cliente bloqueado em **Sales → Customers** ou na 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 observações adicionadas pela sua equipe desde então. Clique em **Add Note** para registrar um novo contexto, como o resultado de um chargeback. As observações podem ser editadas posteriormente.
* **Reference IDs**: O customer ID vinculado a este bloqueio, pronto para ser copiado.

## Desbloqueando um cliente

Clique em **Unblock Customer** na página do cliente ou use o menu de ações na página Blocklist.

* As alterações no Checkout e no Customer Portal são restauradas imediatamente.
* **As subscriptions canceladas não são reativadas.** O cliente precisa comprar novamente.
* A entrada é mantida como registro de auditoria junto com suas observações, mas não aparece mais na lista ativa.
* 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 somente nos logs do Dodo Payments.
* **No Customer Portal**, tudo fica visível, mas todas as ações são desativadas. Uma operação de escrita bloqueada retorna `PORTAL_ACTION_NOT_PERMITTED` com a mensagem "This action is not available." O perfil do portal contém `read_only: true` para que uma integração personalizada do portal possa desativar seus próprios controles. O portal nunca expõe a entrada da lista de bloqueio nem suas observações.

<Warning>
  Se você renderizar erros de checkout ou do portal em seu próprio produto, mantenha esse comportamento. Exiba uma mensagem genérica para `PAYMENT_NOT_PERMITTED` e `PORTAL_ACTION_NOT_PERMITTED`. Revelar o bloqueio informa ao fraudador que ele deve tentar outro email.
</Warning>

## Usando a API

A API da lista de bloqueio permite bloquear clientes a partir das suas próprias ferramentas, por exemplo quando chega um chargeback. Ela exige sua [API key](/api-reference/introduction) secreta. Qualquer chave pode listar entradas e ler observações. Uma chave com **write access** habilitado pode bloquear, desbloquear e gerenciar observações. 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.

| Method   | Endpoint                                          | Purpose                                                        |
| -------- | ------------------------------------------------- | -------------------------------------------------------------- |
| `GET`    | `/blocklist/customers`                            | Listar clientes bloqueados, com filtros e uma contagem `total` |
| `POST`   | `/blocklist/customers`                            | Bloquear um cliente por customer ID ou email                   |
| `GET`    | `/blocklist/customers/{entry_id}`                 | Obter uma entrada junto com suas observações                   |
| `DELETE` | `/blocklist/customers/{entry_id}`                 | Desbloquear um cliente                                         |
| `POST`   | `/blocklist/customers/{entry_id}/notes`           | Adicionar uma observação                                       |
| `PATCH`  | `/blocklist/customers/{entry_id}/notes/{note_id}` | Atualizar uma observação                                       |

### Bloquear um cliente

Envie `customer_id` ou `email` no nível superior do body. `reason` é opcional e aparece na página da entrada.

<CodeGroup>
  ```typescript Node.js 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 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"
    }'
  ```
</CodeGroup>

```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
}
```

| Field                        | Description                                                                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `identifier`                 | O customer ID ou email enviado por você.                                                                                                |
| `source`                     | De onde veio o bloqueio: `blocklist_page`, `customer_page`, `payment_page`, `dispute_page` ou `api`. Uma API key sempre registra `api`. |
| `blocked_by_email`           | O usuário do dashboard que adicionou o bloqueio. `null` para uma API key.                                                               |
| `cancelled_subscription_ids` | Subscriptions canceladas por esta chamada.                                                                                              |
| `remaining_subscription_ids` | Subscriptions que continuam ativas porque um cancelamento falhou ou a chamada atingiu o limite de 25 cancelamentos.                     |
| `subscriptions_swept`        | `false` quando ainda houver live subscriptions. Repita a chamada até que 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 haja subscriptions aguardando cancelamento. Nesse caso, a chamada continua o cancelamento.
</Note>

### Verificar se um cliente está bloqueado

[Get Customer Detail](/api-reference/customers/get-customers-1) 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 associada. O endpoint [List Customers](/api-reference/customers/get-customers) mantém ambos vazios.

### Desbloquear um cliente

<CodeGroup>
  ```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"
  ```
</CodeGroup>

O endpoint retorna HTTP `204` em caso de sucesso. O desbloqueio restaura as operações de escrita no checkout e no portal, mas não reativa nenhuma subscription.

## Práticas recomendadas

* **Registre o motivo.** Um motivo curto no bloqueio, junto com observações sobre tudo que acontecer depois, fornece à sua equipe de suporte o contexto completo sem sair do dashboard.
* **Bloqueie após um chargeback.** Abra o cliente a partir da disputa ou do pagamento e bloqueie-o ali, ou automatize isso a partir do webhook `dispute.opened` com `POST /blocklist/customers`. Consulte [Disputes](/features/transactions/disputes).
* **Verifique `subscriptions_swept`.** Ao bloquear pela API, repita a chamada até que a resposta informe `true`, para que nenhuma live subscription fique ativa.
* **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

<CardGroup cols={2}>
  <Card title="Customer Management" icon="user-group" href="/features/customers">
    Encontre um cliente, abra a página de detalhes e gerencie suas subscriptions.
  </Card>

  <Card title="Customer Portal" icon="id-card" href="/features/customer-portal">
    O que um cliente bloqueado pode e não pode fazer no portal.
  </Card>

  <Card title="Disputes" icon="circle-exclamation" href="/features/transactions/disputes">
    Responda a chargebacks e decida quando um bloqueio é justificável.
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/error-codes">
    O que `PAYMENT_NOT_PERMITTED` e `PORTAL_ACTION_NOT_PERMITTED` significam.
  </Card>
</CardGroup>