> ## 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.
Customer Blocklist impide que un actor malicioso conocido vuelva a comprarte. Un cliente bloqueado no puede pagar, pierde sus suscripciones activas y puede ver su cuenta en el [Customer Portal](/features/customer-portal), pero no puede cambiar sus suscripciones. Administra la lista de bloqueados desde **Settings → Blocklist** o mediante la API de Blocklist.
## Qué sucede al bloquear a un cliente
El bloqueo entra en vigor en cuanto lo añades, en cada una de estas áreas:
| Área | Efecto |
| - | - |
| **Checkout** | Se rechaza todo intento de pago del email bloqueado: payment links, checkout sessions y pagos o suscripciones creados mediante la API. |
| **Live subscriptions** | 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. |
| **Renewals and retries** | Las renovaciones automáticas y los [payment retries](/features/recovery/payment-retries) omiten al cliente bloqueado, por lo que no se realiza ningún cargo adicional aunque la cancelación aún esté pendiente. |
| **Manual retry** | Se rechaza un [manual retry](/features/recovery/manual-retry) del pago de un cliente bloqueado. |
| **Customer Portal** | El cliente puede iniciar sesión y ver facturas, suscripciones y claves de licencia. No puede cancelar, pausar ni reanudar una suscripción, cambiar de plan, actualizar un método de pago ni editar la dirección de facturación. Aún puede 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 [Refunds](/features/transactions/refunds).
## Cómo se compara con los clientes el bloqueo
Puedes bloquear por **customer ID** o por **email**. En cualquier caso, el bloqueo se basa en el email del cliente, no en el registro del cliente:
* **Se incluyen todos los registros con ese email.** Checkout puede crear un nuevo registro de cliente para un email recurrente, por lo que un bloqueo basado en un único customer ID podría eludirse. Un bloqueo basado en el email no puede eludirse.
* **Se incluyen los alias.** Los emails se comparan en minúsculas y con cualquier `+alias` eliminado, 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.
* **Limitado a tu empresa.** El bloqueo solo se aplica a tu empresa. El mismo email aún puede comprar a otras empresas en Dodo Payments.
* **El email debe pertenecer a un cliente existente.** No puedes bloquear un email que no coincida con ninguno de tus clientes ni un registro de cliente que no tenga email.
## Bloquear un cliente
Puedes bloquear a un cliente desde la página Blocklist o desde la propia página del cliente.
Ve a **Settings → Blocklist** en tu dashboard.
Haz clic en **Add to Blocklist** e introduce el email o el customer ID del cliente en **Customer ID or email**. El panel muestra el cliente coincidente.
Haz clic en **Add to Blocklist** en el panel. Las suscripciones activas del cliente se cancelan inmediatamente y la entrada aparece en la tabla **Blocked entries**. Si algunas suscripciones aún se están cancelando, el dashboard muestra un aviso. Actualiza la página después de un momento para comprobarlo.
Ve a **Sales → Customers** y abre el cliente que quieres bloquear.
Abre el menú con el icono de tres puntos y selecciona **Block this Customer**.
Haz clic en **Block**. Cuando el bloqueo esté activo, la página mostrará una insignia **Blocked** junto al nombre del cliente.
El dashboard no solicita ningún motivo. Para registrar por qué bloqueaste al cliente, añade una nota en su página o envía `reason` cuando bloquees mediante la API.
## Administrar 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 (email o customer ID), **Blocked By** y **Blocked On**. **Blocked By** muestra al miembro del equipo que añadió el bloqueo o **API** si se añadió mediante una API key.
* **Search Identifier** y **Filters**: Busca una entrada por email o customer ID, o filtra por **Blocked By** y **Blocked Between**.
* **Action**: **See Details** abre la página del cliente bloqueado y **Unblock** elimina el bloqueo. Los miembros del equipo con el rol **Viewer** no pueden desbloquear.
### 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 bloqueados, el motivo y las notas que tu equipo haya añadido desde entonces. Haz clic en **Add Note** para registrar información nueva, como el resultado de un chargeback. Puedes editar una nota más adelante mediante la API.
* **Reference IDs**: El customer ID vinculado a este bloqueo, listo para copiar.
## Desbloquear un cliente
Para desbloquear a un cliente, haz clic en **Unblock Customer** en su página o selecciona **Unblock** en la columna **Action** de la página Blocklist. Después, confirma con **Unblock**.
* Los cambios en Checkout y Customer Portal se restauran inmediatamente.
* **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. Eso crea una entrada nueva.
## Lo que 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 se rechaza cualquier acción que cambie la cuenta. Una acción rechazada devuelve HTTP `403` con `PORTAL_ACTION_NOT_PERMITTED` y el mensaje "This action is not available." El perfil del portal incluye `read_only: true`, por lo que una integración personalizada del portal puede desactivar sus propios controles. El portal nunca muestra la entrada de la lista de bloqueados ni sus notas.
Si renderizas 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 debe probar con otro email.
## Usar la API
La API de Blocklist te permite bloquear desde tus propias herramientas, por ejemplo cuando llega un chargeback. Requiere tu [API key](/api-reference/introduction) secreta. Cualquier key puede enumerar entradas y leer notas. Una key con **write access** habilitado puede bloquear, desbloquear y administrar notas. El dashboard aplica la misma separación a los roles del equipo: el rol **Viewer** puede leer la lista y el rol **Editor** puede realizar cambios.
La API de Blocklist tiene seis endpoints:
| Method | Endpoint | Purpose |
| - | - | - |
| `GET` | `/blocklist/customers` | Enumerar clientes bloqueados, con filtros y un recuento `total` |
| `POST` | `/blocklist/customers` | Bloquear un cliente por customer ID o email |
| `GET` | `/blocklist/customers/{entry_id}` | Obtener una entrada junto con sus notas |
| `DELETE` | `/blocklist/customers/{entry_id}` | Desbloquear un cliente |
| `POST` | `/blocklist/customers/{entry_id}/notes` | Añadir una nota |
| `PATCH` | `/blocklist/customers/{entry_id}/notes/{note_id}` | Actualizar una nota |
La lista solo devuelve bloqueos activos. Para filtrarla, envía `identifier` (una coincidencia parcial que no distingue mayúsculas y minúsculas en el email o customer ID), `blocked_by_email`, `created_at_gte` o `created_at_lte`. De forma predeterminada, devuelve 10 entradas por página: establece `page_size` para devolver hasta 100 y `page_number` para recorrer las páginas.
### Bloquear un cliente
Envía `customer_id` o `email` en el nivel superior del body. Si envías ambos, el bloqueo usa `customer_id`. `reason` es opcional y aparece en la página de la entrada. Un bloqueo nuevo devuelve 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"
}'
```
La respuesta describe la entrada y las suscripciones que la llamada canceló:
```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
}
```
Estos son los campos que requieren mayor atención:
| Field | Description |
| - | - |
| `identifier` | El customer ID o email que enviaste. |
| `source` | De dónde procede el bloqueo: `blocklist_page`, `customer_page`, `payment_page`, `dispute_page` o `api`. Una API key siempre registra `api`, independientemente del `source` que envíes. |
| `blocked_by_email` | El usuario del dashboard que añadió el bloqueo. `null` para una API key. |
| `cancelled_subscription_ids` | Las suscripciones que esta llamada canceló. Solo está presente en la respuesta de creación. |
| `remaining_subscription_ids` | Suscripciones que siguen activas porque falló una cancelación o porque la llamada alcanzó su límite de 25 cancelaciones. |
| `subscriptions_swept` | `false` cuando quedan suscripciones activas o cuando Dodo Payments no pudo enumerarlas. Repite la llamada hasta que sea `true`. El bloqueo ya está activo. |
Bloquear a un cliente que ya está bloqueado devuelve HTTP `409` con `CUSTOMER_ALREADY_BLOCKED`, a menos que todavía haya suscripciones pendientes de cancelación. En ese caso, la llamada continúa la cancelación y devuelve HTTP `200`.
### 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 que lo respalda. El endpoint [List Customers](/api-reference/customers/get-customers) deja ambos campos vacíos.
### Desbloquear 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 y HTTP `404` cuando el ID no coincide con ningún bloqueo activo. Desbloquear restaura las operaciones de escritura en Checkout y el portal, y no reactiva ninguna suscripción.
## Prácticas recomendadas
* **Registra el motivo.** Un motivo breve en el bloqueo, junto con notas sobre cualquier evento posterior, proporciona a tu equipo de soporte toda la información sin salir del dashboard.
* **Bloquea después de un chargeback.** Abre la página del 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 [Disputes](/features/transactions/disputes).
* **Comprueba `subscriptions_swept`.** Cuando bloquees mediante la API, repite la llamada hasta que la respuesta indique `true`, para no dejar 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 administra sus suscripciones.
Lo que un cliente bloqueado puede y no puede hacer en el portal.
Responde a chargebacks y decide cuándo está justificado un bloqueo.
Qué significan `PAYMENT_NOT_PERMITTED` e `PORTAL_ACTION_NOT_PERMITTED`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.