> ## 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. # Blocklist clienti > Blocca un cliente per impedire futuri checkout, annullare i suoi abbonamenti attivi e rendere il suo Customer Portal di sola lettura. Gestisci la blocklist da Impostazioni o tramite API. La Customer Blocklist impedisce a un soggetto fraudolento noto di acquistare nuovamente da te. Un cliente bloccato non può pagare, perde i suoi abbonamenti attivi e può visualizzare, ma non modificare, nulla nel [Customer Portal](/features/customer-portal). Gestiscila da **Impostazioni → Blocklist** o tramite la Blocklist API. Pagina delle impostazioni della blocklist che mostra il numero totale di clienti bloccati, una tabella delle voci bloccate con le colonne identificatore, bloccato da e bloccato il, e un pulsante Aggiungi alla blocklist ## Cosa succede quando blocchi un cliente | Area | Effetto | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Checkout** | Ogni tentativo di pagamento dall'email bloccata viene rifiutato: payment links, checkout sessions e pagamenti o abbonamenti creati tramite API. | | **Abbonamenti attivi** | Gli abbonamenti con stato `pending`, `active`, `on_hold` o `paused` vengono annullati con il motivo `cancelled_by_merchant`. Il webhook `subscription.cancelled` standard viene attivato per ciascuno. | | **Rinnovi e tentativi** | I rinnovi automatici e i [nuovi tentativi di pagamento](/features/recovery/payment-retries) ignorano un cliente bloccato, quindi non vengono effettuati altri addebiti anche se un annullamento è ancora in attesa. | | **Nuovo tentativo manuale** | Un [nuovo tentativo manuale](/features/recovery/manual-retry) del pagamento di un cliente bloccato viene rifiutato. | | **Customer Portal** | Il cliente può ancora accedere e visualizzare fatture, abbonamenti e chiavi di licenza, ma non può annullare, mettere in pausa o riprendere un abbonamento, cambiare piano o aggiornare un metodo di pagamento. La rimozione di un metodo di pagamento salvato rimane consentita. | Il blocco non rimborsa i pagamenti passati e non influisce sulle contestazioni aperte. Emetti eventuali rimborsi separatamente dalla pagina [Rimborsi](/features/transactions/refunds). ## Come il blocco identifica i clienti Puoi bloccare tramite **ID cliente** o **email**. In entrambi i casi, il blocco si basa sull'email del cliente, non sul record del cliente: * **Sono inclusi tutti i record con quell'email.** Il checkout può creare un nuovo record cliente per un'email già utilizzata, quindi un blocco su un singolo ID cliente potrebbe essere aggirato. Un blocco sull'email invece no. * **Gli alias sono inclusi.** Le email vengono confrontate in minuscolo, rimuovendo `+alias`, quindi `buyer+promo@example.com` e `Buyer@example.com` vengono considerati lo stesso cliente. I punti nell'indirizzo vengono mantenuti così come sono. * **Limitato alla tua attività.** Un blocco si applica solo alla tua attività. La stessa email può ancora acquistare da altre attività su Dodo Payments. * **L'email deve appartenere a un cliente esistente.** Non puoi bloccare un'email che non ha mai effettuato un checkout con te e non è possibile bloccare un record cliente privo di email. ## Bloccare un cliente Vai su **Impostazioni → Blocklist** nella dashboard. Fai clic su **Aggiungi alla blocklist**, quindi inserisci l'email o l'ID cliente. Aggiungi un motivo, così il tuo team potrà sapere in seguito perché è stato aggiunto il blocco. Conferma il blocco. Gli abbonamenti attivi del cliente vengono annullati immediatamente e la voce appare nella tabella **Voci bloccate**. Vai su **Vendite → Clienti** e apri il cliente che vuoi bloccare. Fai clic su **Blocca cliente**. Quando il blocco è attivo, la pagina mostra un badge **Bloccato** accanto al nome del cliente. ## Gestire i clienti bloccati La pagina **Blocklist** elenca tutti i blocchi attivi: * **Totale clienti bloccati**: quanti clienti sono attualmente bloccati. * **Voci bloccate**: una riga per ogni blocco, con l'**Identificatore** inserito (email o ID cliente), **Bloccato da** (il membro del team che ha aggiunto il blocco) e **Bloccato il**. * **Cerca identificatore** e **Filtri**: trova una voce tramite email o ID cliente oppure filtra in base a chi l'ha bloccata e quando. * **Azione**: gestisci la voce, incluso lo sblocco del cliente. ### La pagina del cliente bloccato Pagina Informazioni cliente per un cliente bloccato che mostra il badge Bloccato, un pulsante Sblocca cliente, un Registro attività con una nota e l'evento Aggiunto alla blocklist, e un pannello ID di riferimento con l'ID cliente Apri un cliente bloccato da **Vendite → Clienti** o dalla pagina Blocklist per visualizzare: * Un badge **Bloccato** accanto al nome del cliente e un pulsante **Sblocca cliente**. * **Registro attività**: quando il cliente è stato aggiunto alla blocklist, il motivo ed eventuali note aggiunte in seguito dal tuo team. Fai clic su **Aggiungi nota** per registrare nuovo contesto, ad esempio l'esito di un chargeback. Le note possono essere modificate in seguito. * **ID di riferimento**: l'ID cliente collegato a questo blocco, pronto per essere copiato. ## Sbloccare un cliente Fai clic su **Sblocca cliente** nella pagina del cliente oppure usa il menu delle azioni nella pagina Blocklist. * Le modifiche al checkout e al Customer Portal vengono ripristinate immediatamente. * **Gli abbonamenti annullati non vengono riattivati.** Il cliente deve effettuare nuovamente l'acquisto. * La voce viene conservata come record di audit insieme alle relative note, ma non appare più nell'elenco attivo. * Puoi bloccare nuovamente lo stesso cliente in seguito. Verrà creata una nuova voce. ## Cosa vede il cliente A un cliente bloccato non viene mai comunicato che è stato bloccato. * **Durante il checkout**, il pagamento non va a buon fine con un rifiuto generico: "Questo pagamento non può essere elaborato." L'API restituisce HTTP `403` con il codice di errore `PAYMENT_NOT_PERMITTED`, che non specifica alcuna causa. Il motivo reale viene scritto solo nei log di Dodo Payments. * **Nel Customer Portal**, tutto è visibile, ma ogni azione è disabilitata. Una richiesta di modifica bloccata restituisce `PORTAL_ACTION_NOT_PERMITTED` con il messaggio "Questa azione non è disponibile." Il profilo del portale contiene `read_only: true`, così un'integrazione personalizzata del portale può disabilitare i propri controlli. Il portale non mostra mai la voce della blocklist né le relative note. Se visualizzi gli errori del checkout o del portale nel tuo prodotto, mantieni questo comportamento. Mostra un messaggio generico per `PAYMENT_NOT_PERMITTED` e `PORTAL_ACTION_NOT_PERMITTED`. Rivelare il blocco comunica a un soggetto fraudolento di provare un'altra email. ## Utilizzare l'API La Blocklist API ti permette di bloccare i clienti dai tuoi strumenti, ad esempio quando arriva un chargeback. Richiede la tua [chiave API](/api-reference/introduction) segreta. Qualsiasi chiave può elencare le voci e leggere le note. Una chiave con **accesso in scrittura** abilitato può bloccare, sbloccare e gestire le note. La dashboard applica la stessa distinzione ai ruoli del team: il ruolo **Visualizzatore** legge l'elenco, mentre il ruolo **Editor** apporta modifiche. | Metodo | Endpoint | Scopo | | -------- | ------------------------------------------------- | ------------------------------------------------------------ | | `GET` | `/blocklist/customers` | Elenca i clienti bloccati, con filtri e un conteggio `total` | | `POST` | `/blocklist/customers` | Blocca un cliente tramite ID cliente o email | | `GET` | `/blocklist/customers/{entry_id}` | Recupera una voce insieme alle relative note | | `DELETE` | `/blocklist/customers/{entry_id}` | Sblocca un cliente | | `POST` | `/blocklist/customers/{entry_id}/notes` | Aggiunge una nota | | `PATCH` | `/blocklist/customers/{entry_id}/notes/{note_id}` | Aggiorna una nota | ### Bloccare un cliente Invia `customer_id` o `email` al livello principale del body. `reason` è facoltativo e viene visualizzato nella pagina della voce. ```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 | Descrizione | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `identifier` | L'ID cliente o l'email inviati. | | `source` | Origine del blocco: `blocklist_page`, `customer_page`, `payment_page`, `dispute_page` o `api`. Una chiave API registra sempre `api`. | | `blocked_by_email` | L'utente della dashboard che ha aggiunto il blocco. `null` per una chiave API. | | `cancelled_subscription_ids` | Gli abbonamenti annullati da questa chiamata. | | `remaining_subscription_ids` | Gli abbonamenti ancora attivi perché un annullamento non è riuscito o la chiamata ha raggiunto il limite di 25 annullamenti. | | `subscriptions_swept` | `false` quando rimangono abbonamenti attivi. Ripeti la chiamata finché non è `true`. Il blocco è già attivo. | Bloccare un cliente già bloccato restituisce HTTP `409` con `CUSTOMER_ALREADY_BLOCKED`, a meno che ci siano ancora abbonamenti in attesa di essere annullati. In tal caso la chiamata prosegue invece con l'annullamento. ### Verificare se un cliente è bloccato [Get Customer Detail](/api-reference/customers/get-customers-1) restituisce due campi aggiuntivi: `blocked_at`, l'ora in cui è stato aggiunto il blocco attivo (`null` quando il cliente non è bloccato), e `blocklist_entry_id`, la voce alla base del blocco. L'endpoint [List Customers](/api-reference/customers/get-customers) lascia vuoti entrambi i campi. ### Sbloccare 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" ``` L'endpoint restituisce HTTP `204` in caso di successo. Lo sblocco ripristina le modifiche al checkout e al portale e non riattiva alcun abbonamento. ## Best practice * **Registra il motivo.** Un breve motivo sul blocco, insieme alle note per qualsiasi evento successivo, fornisce al team di supporto il quadro completo senza dover uscire dalla dashboard. * **Blocca dopo un chargeback.** Apri il cliente dalla contestazione o dal pagamento e bloccalo da lì, oppure automatizza l'operazione dal webhook `dispute.opened` con `POST /blocklist/customers`. Vedi [Contestazioni](/features/transactions/disputes). * **Controlla `subscriptions_swept`.** Quando blocchi tramite API, ripeti la chiamata finché la risposta non restituisce `true`, così non rimane alcun abbonamento attivo. * **Rimborsa separatamente.** Un blocco impedisce solo gli acquisti futuri. Se devi del denaro al cliente, rimborsa il pagamento come di consueto. * **Controlla l'elenco.** Sblocca i clienti il cui problema è stato risolto. Lo sblocco è immediato e conserva la cronologia. ## Correlati Trova un cliente, apri la pagina dei dettagli e gestisci i suoi abbonamenti. Cosa può e non può fare un cliente bloccato nel portale. Rispondi ai chargeback e decidi quando è opportuno applicare un blocco. Cosa significano `PAYMENT_NOT_PERMITTED` e `PORTAL_ACTION_NOT_PERMITTED`.