> ## 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 bloqueo de clientes
> Bloquea a un cliente para impedir futuras compras, cancelar sus suscripciones activas y hacer que su Customer Portal sea de solo lectura. Gestiona la lista de bloqueo desde Settings o la API.
La lista de bloqueo de clientes impide que un actor malicioso conocido vuelva a comprarte. Un cliente bloqueado no puede pagar, pierde sus suscripciones activas y puede consultar, pero no modificar nada en el [Customer Portal](/features/customer-portal). Gestiona la lista desde **Settings → Blocklist** o mediante la API de la lista de bloqueo.
## Qué sucede al bloquear a un cliente
| Área | Efecto |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Checkout** | Se rechaza todo intento de pago desde el correo electrónico bloqueado: payment links, checkout sessions y pagos o suscripciones creados mediante la API. |
| **Suscripciones activas** | Las suscripciones con estado `pending`, `active`, `on_hold` o `paused` se cancelan con el motivo `cancelled_by_merchant`. El webhook habitual `subscription.cancelled` se activa para cada una. |
| **Renovaciones y reintentos** | Las renovaciones automáticas y los [reintentos de pago](/features/recovery/payment-retries) omiten al cliente bloqueado, por lo que no se realiza ningún cargo adicional aunque la cancelación siga pendiente. |
| **Reintento manual** | Se rechaza un [reintento manual](/features/recovery/manual-retry) del pago de un cliente bloqueado. |
| **Customer Portal** | El cliente puede iniciar sesión y consultar facturas, suscripciones y claves de licencia, pero no puede cancelar, pausar ni reanudar una suscripción, cambiar de plan ni actualizar un método de pago. Se permite eliminar un método de pago guardado. |
El bloqueo no reembolsa pagos anteriores ni afecta a disputas abiertas. Emite cualquier reembolso por separado desde la página de [Reembolsos](/features/transactions/refunds).
## Cómo se relaciona el bloqueo con los clientes
Puedes bloquear por **ID de cliente** o por **correo electrónico**. En ambos casos, el bloqueo se basa en el correo electrónico del cliente, no en el registro del cliente:
* **Se incluyen todos los registros con ese correo electrónico.** Checkout puede crear un nuevo registro de cliente para un correo que vuelve a comprar, por lo que un bloqueo de un único ID de cliente podría eludirse. Un bloqueo por correo electrónico no puede eludirse de esta forma.
* **Se incluyen los alias.** Los correos electrónicos se comparan en minúsculas y sin `+alias`, por lo que `buyer+promo@example.com` e `Buyer@example.com` se consideran el mismo cliente. Los puntos de la dirección se conservan tal como están.
* **El alcance se limita a tu negocio.** El bloqueo solo se aplica a tu negocio. El mismo correo electrónico puede seguir comprando a otros negocios en Dodo Payments.
* **El correo electrónico debe pertenecer a un cliente existente.** No puedes bloquear un correo que nunca haya completado un checkout contigo, y no se puede bloquear un registro de cliente sin correo electrónico.
## Bloquear a un cliente
Ve a **Settings → Blocklist** en tu dashboard.
Haz clic en **Add to Blocklist** e introduce el correo electrónico o el ID de cliente. Añade un motivo para que tu equipo pueda ver más adelante por qué se añadió el bloqueo.
Confirma el bloqueo. Las suscripciones activas del cliente se cancelan de inmediato y la entrada aparece en la tabla **Blocked entries**.
Ve a **Sales → Customers** y abre el cliente que quieres bloquear.
Haz clic en **Block Customer**. Cuando el bloqueo entre en vigor, la página mostrará una insignia **Blocked** junto al nombre del cliente.
## Gestionar clientes bloqueados
La página **Blocklist** muestra todos los bloqueos activos:
* **Total Customers Blocked**: Cuántos clientes están bloqueados actualmente.
* **Blocked entries**: Una fila por bloqueo, con el **Identifier** que introdujiste (correo electrónico o ID de cliente), **Blocked By** (el miembro del equipo que añadió el bloqueo) y **Blocked On**.
* **Search Identifier** y **Filters**: Busca una entrada por correo electrónico o ID de cliente, o filtra por quién la bloqueó y cuándo.
* **Action**: Gestiona la entrada, incluido desbloquear al cliente.
### Página del cliente bloqueado
Abre un cliente bloqueado desde **Sales → Customers** o desde la página Blocklist para ver:
* Una insignia **Blocked** junto al nombre del cliente y un botón **Unblock Customer**.
* **Activity Log**: Cuándo se añadió el cliente a la lista de bloqueo, el motivo y las notas que tu equipo haya añadido posteriormente. Haz clic en **Add Note** para registrar información adicional, como el resultado de un contracargo. Las notas se pueden editar más adelante.
* **Reference IDs**: El ID de cliente vinculado a este bloqueo, listo para copiar.
## Desbloquear a un cliente
Haz clic en **Unblock Customer** en la página del cliente o usa el menú de acciones de la página Blocklist.
* Checkout y los cambios en Customer Portal se restablecen de inmediato.
* **Las suscripciones canceladas no se reactivan.** El cliente debe volver a comprar.
* La entrada se conserva como registro de auditoría junto con sus notas, pero ya no aparece en la lista activa.
* Puedes volver a bloquear al mismo cliente más adelante. Esto crea una nueva entrada.
## Qué ve el cliente
Nunca se informa a un cliente bloqueado de que ha sido bloqueado.
* **En Checkout**, el pago falla con un rechazo genérico: "This payment cannot be processed." La API devuelve HTTP `403` con el código de error `PAYMENT_NOT_PERMITTED`, que no indica ninguna causa. El motivo real solo se registra en los logs de Dodo Payments.
* **En Customer Portal**, todo es visible, pero todas las acciones están deshabilitadas. Una escritura bloqueada devuelve `PORTAL_ACTION_NOT_PERMITTED` con el mensaje "This action is not available." El perfil del portal incluye `read_only: true` para que una integración personalizada del portal pueda deshabilitar sus propios controles. El portal nunca muestra la entrada de la lista de bloqueo ni sus notas.
Si muestras errores de checkout o del portal en tu propio producto, conserva este comportamiento. Muestra un mensaje genérico para `PAYMENT_NOT_PERMITTED` e `PORTAL_ACTION_NOT_PERMITTED`. Revelar el bloqueo indica a un actor malicioso que pruebe con otro correo electrónico.
## Usar la API
La API de la lista de bloqueo te permite bloquear desde tus propias herramientas, por ejemplo cuando llega un contracargo. Requiere tu [clave de API](/api-reference/introduction) secreta. Cualquier clave puede enumerar entradas y leer notas. Una clave con **write access** habilitado puede bloquear, desbloquear y gestionar notas. El dashboard aplica la misma separación a los roles del equipo: el rol **Viewer** lee la lista y el rol **Editor** realiza cambios.
| Método | Endpoint | Propósito |
| -------- | ------------------------------------------------- | --------------------------------------------------------------- |
| `GET` | `/blocklist/customers` | Enumerar clientes bloqueados, con filtros y un recuento `total` |
| `POST` | `/blocklist/customers` | Bloquear a un cliente por ID de cliente o correo electrónico |
| `GET` | `/blocklist/customers/{entry_id}` | Obtener una entrada junto con sus notas |
| `DELETE` | `/blocklist/customers/{entry_id}` | Desbloquear a un cliente |
| `POST` | `/blocklist/customers/{entry_id}/notes` | Añadir una nota |
| `PATCH` | `/blocklist/customers/{entry_id}/notes/{note_id}` | Actualizar una nota |
### Bloquear a un cliente
Envía `customer_id` o `email` en el nivel superior del cuerpo. `reason` es opcional y se muestra en la página de la entrada.
```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"
}'
```
```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
}
```
| Campo | Descripción |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `identifier` | El ID de cliente o correo electrónico que enviaste. |
| `source` | De dónde provino el bloqueo: `blocklist_page`, `customer_page`, `payment_page`, `dispute_page` o `api`. Una clave de API siempre registra `api`. |
| `blocked_by_email` | El usuario del dashboard que añadió el bloqueo. `null` para una clave de API. |
| `cancelled_subscription_ids` | Suscripciones que canceló esta llamada. |
| `remaining_subscription_ids` | Suscripciones que siguen activas porque una cancelación falló o la llamada alcanzó su límite de 25 cancelaciones. |
| `subscriptions_swept` | `false` cuando quedan suscripciones activas. Repite la llamada hasta que sea `true`. El bloqueo ya está vigente. |
Bloquear a un cliente que ya está bloqueado devuelve HTTP `409` con `CUSTOMER_ALREADY_BLOCKED`, a menos que aún haya suscripciones pendientes de cancelación. En ese caso, la llamada continúa con la cancelación.
### Comprobar si un cliente está bloqueado
[Get Customer Detail](/api-reference/customers/get-customers-1) devuelve dos campos adicionales: `blocked_at`, la hora en que se añadió el bloqueo activo (`null` cuando el cliente no está bloqueado), e `blocklist_entry_id`, la entrada asociada. El endpoint [List Customers](/api-reference/customers/get-customers) deja ambos campos vacíos.
### Desbloquear a un 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"
```
El endpoint devuelve HTTP `204` cuando tiene éxito. Desbloquear restablece las escrituras de checkout y del portal, pero no reactiva ninguna suscripción.
## Prácticas recomendadas
* **Registra el motivo.** Un motivo breve en el bloqueo, junto con notas sobre lo que ocurra después, proporciona a tu equipo de soporte toda la información sin salir del dashboard.
* **Bloquea después de un contracargo.** Abre el cliente desde la disputa o el pago y bloquéalo allí, o automatiza el proceso desde el webhook `dispute.opened` con `POST /blocklist/customers`. Consulta [Disputas](/features/transactions/disputes).
* **Comprueba `subscriptions_swept`.** Cuando bloquees mediante la API, repite la llamada hasta que la respuesta indique `true`, para que no quede ninguna suscripción activa.
* **Reembolsa por separado.** Un bloqueo solo detiene compras futuras. Si debes dinero al cliente, reembolsa el pago como de costumbre.
* **Revisa la lista.** Desbloquea a los clientes cuyo problema se haya resuelto. El desbloqueo es inmediato y conserva el historial.
## Relacionado
Busca un cliente, abre su página de detalles y gestiona sus suscripciones.
Qué puede y qué no puede hacer un cliente bloqueado en el portal.
Responde a contracargos y decide cuándo está justificado un bloqueo.
Qué significan `PAYMENT_NOT_PERMITTED` e `PORTAL_ACTION_NOT_PERMITTED`.