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, pero no puede cambiar sus suscripciones. Administra la lista de bloqueados desde Settings → Blocklist o mediante la API de Blocklist.

The Blocklist tab under Settings

​

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

​

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 [e-mail] e [e-mail] 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.

From Settings

1. Open the Blocklist

   Ve a Settings → Blocklist en tu dashboard.

2. Add to Blocklist

   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.

3. Confirm

   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.

From the customer's page

1. Open the Customer

   Ve a Sales → Customers y abre el cliente que quieres bloquear.

2. Block the Customer

   Abre el menú con el icono de tres puntos y selecciona Block this Customer.

3. Confirm

   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

A blocked customer's details page

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

Node.js

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: '[e-mail]',
  reason: 'Repeated refund abuse',
});

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

La respuesta describe la entrada y las suscripciones que la llamada canceló:

Response

{
  "id": "bcu_7Hq2mV9kRt4LxYw3Pz",
  "customer_id": "cus_0NmichXWP8JYBB9Dw1Unj",
  "customer_name": "wow guy",
  "customer_email": "[e-mail]",
  "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 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 deja ambos campos vacíos.

​

Desbloquear un cliente

Node.js

await client.blocklist.customers.delete('bcu_7Hq2mV9kRt4LxYw3Pz');

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

Customer Management

Busca un cliente, abre su página de detalles y administra sus suscripciones.

Customer Portal

Lo que un cliente bloqueado puede y no puede hacer en el portal.

Disputes

Responde a chargebacks y decide cuándo está justificado un bloqueo.

Error Codes

Qué significan PAYMENT_NOT_PERMITTED e PORTAL_ACTION_NOT_PERMITTED.