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

# 顧客ブロックリスト

> 顧客をブロックすると、今後のチェックアウトを停止し、現在有効なサブスクリプションをキャンセルし、Customer Portalを読み取り専用にできます。ブロックリストはSettingsまたはAPIから管理できます。

<Info>
  顧客ブロックリストは、悪意のあることが分かっている顧客が再び購入するのを防ぎます。ブロックされた顧客は支払いができず、有効なサブスクリプションを失い、[Customer Portal](/features/customer-portal)では内容を表示できますが変更はできません。**Settings → Blocklist**またはBlocklist APIから管理できます。
</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="ブロックされた顧客の合計数、識別子・ブロックしたユーザー・ブロック日時の列を含むブロック済みエントリのテーブル、Add to Blocklistボタンを表示するブロックリスト設定ページ" style={{ maxHeight: '500px', width: 'auto' }} width="2358" height="1554" data-path="images/blocklist/blocklist-settings.png" />
</Frame>

## 顧客をブロックするとどうなるか

| 項目                  | 影響                                                                                                                                              |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Checkout**        | ブロックされたメールアドレスからのすべての支払い試行が拒否されます。対象はpayment links、checkout sessions、APIを通じて作成された支払いまたはサブスクリプションです。                                             |
| **有効なサブスクリプション**    | `pending`、`active`、`on_hold`、または`paused`ステータスのサブスクリプションは、理由`cancelled_by_merchant`でキャンセルされます。それぞれについて通常の`subscription.cancelled` webhookが発生します。 |
| **更新と再試行**          | 自動更新と[payment retries](/features/recovery/payment-retries)では、ブロックされた顧客がスキップされます。そのため、キャンセルがまだ保留中であっても、それ以降の請求は行われません。                           |
| **手動再試行**           | ブロックされた顧客の支払いに対する[manual retry](/features/recovery/manual-retry)は拒否されます。                                                                        |
| **Customer Portal** | 顧客は引き続きログインして請求書、サブスクリプション、ライセンスキーを表示できますが、サブスクリプションのキャンセル・一時停止・再開、プラン変更、支払い方法の更新はできません。保存済みの支払い方法の削除は引き続き許可されます。                               |

<Note>
  ブロックしても過去の支払いは返金されず、進行中のdisputesにも影響しません。返金を行う場合は、[Refunds](/features/transactions/refunds)ページから別途実行してください。
</Note>

## 顧客とのブロック照合方法

**customer ID**または**email**でブロックできます。どちらの場合も、ブロックは顧客レコードではなく顧客のメールアドレスをキーにします。

* **そのメールアドレスを持つすべてのレコードが対象になります。** 再来店した顧客のメールアドレスでCheckoutから新しい顧客レコードが作成される可能性があるため、1つのcustomer IDだけをブロックすると回避される可能性があります。メールアドレスをブロックすれば回避できません。
* **エイリアスも対象になります。** メールアドレスは小文字に変換され、`+alias`を削除したうえで比較されるため、`buyer+promo@example.com`と`Buyer@example.com`は同じ顧客として扱われます。アドレス内のドットはそのまま保持されます。
* **ビジネス単位で適用されます。** ブロックはお客様のビジネスにのみ適用されます。同じメールアドレスの顧客が、Dodo Payments上の他のビジネスから購入することは可能です。
* **メールアドレスは既存の顧客に属している必要があります。** お客様のサービスで一度もチェックアウトしていないメールアドレスはブロックできません。また、メールアドレスのない顧客レコードもブロックできません。

## 顧客をブロックする

<Tabs>
  <Tab title="From Settings">
    <Steps>
      <Step title="Open the Blocklist">
        ダッシュボードで**Settings → Blocklist**に移動します。
      </Step>

      <Step title="Add to Blocklist">
        **Add to Blocklist**をクリックし、顧客のメールアドレスまたはcustomer IDを入力します。後でチームがブロックの理由を確認できるよう、理由を追加してください。
      </Step>

      <Step title="Confirm">
        ブロックを確定します。顧客の有効なサブスクリプションは直ちにキャンセルされ、エントリが**Blocked entries**テーブルに表示されます。
      </Step>
    </Steps>
  </Tab>

  <Tab title="From the customer's page">
    <Steps>
      <Step title="Open the customer">
        **Sales → Customers**に移動し、ブロックする顧客を開きます。
      </Step>

      <Step title="Block the customer">
        **Block Customer**をクリックします。ブロックが有効になると、顧客名の横に**Blocked**バッジが表示されます。
      </Step>
    </Steps>
  </Tab>
</Tabs>

## ブロックされた顧客の管理

**Blocklist**ページには、現在有効なすべてのブロックが一覧表示されます。

* **Total Customers Blocked**：現在ブロックされている顧客数です。
* **Blocked entries**：ブロック1件につき1行表示されます。入力した**Identifier**（メールアドレスまたはcustomer ID）、**Blocked By**（ブロックを追加したチームメンバー）、**Blocked On**が含まれます。
* **Search Identifier**と**Filters**：メールアドレスまたはcustomer IDでエントリを検索したり、ブロックしたユーザーや日時で絞り込んだりできます。
* **Action**：顧客のブロック解除など、エントリを管理します。

### ブロックされた顧客のページ

<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="Blockedバッジ、Unblock Customerボタン、メモとAdded to blocklistイベントを含むActivity Log、customer IDを含むReference IDsパネルを表示する、ブロックされた顧客のCustomer Informationページ" style={{ maxHeight: '500px', width: 'auto' }} width="2366" height="1554" data-path="images/blocklist/blocked-customer-details.png" />
</Frame>

**Sales → Customers**またはBlocklistページからブロックされた顧客を開くと、次の内容を確認できます。

* 顧客名の横に表示される**Blocked**バッジと、**Unblock Customer**ボタン。
* **Activity Log**：顧客がブロックリストに追加された日時、理由、それ以降にチームが追加したメモ。**Add Note**をクリックすると、チャージバックの結果など、新しい情報を記録できます。メモは後から編集できます。
* **Reference IDs**：このブロックに紐づくcustomer IDをコピーできます。

## 顧客のブロックを解除する

顧客のページで**Unblock Customer**をクリックするか、Blocklistページのアクションメニューを使用します。

* CheckoutとCustomer Portalでの変更が直ちに復元されます。
* **キャンセルされたサブスクリプションは再開されません。** 顧客は再度購入する必要があります。
* エントリはメモとともに監査記録として保持されますが、有効なリストには表示されなくなります。
* 後から同じ顧客を再びブロックできます。その場合は新しいエントリが作成されます。

## 顧客に表示される内容

ブロックされた顧客に、ブロックされたことが通知されることはありません。

* **Checkoutでは**、支払いが一般的な拒否メッセージ「This payment cannot be processed.」で失敗します。APIはエラーコード`PAYMENT_NOT_PERMITTED`とともにHTTP `403`を返しますが、原因は示されません。実際の理由はDodo Paymentsのログにのみ記録されます。
* **Customer Portalでは**、すべての内容を表示できますが、すべての操作が無効になります。ブロックされた書き込み操作は、メッセージ「This action is not available.」とともに`PORTAL_ACTION_NOT_PERMITTED`を返します。ポータルのプロフィールには`read_only: true`が付与されるため、カスタムポータル統合で独自のコントロールを無効にできます。ポータルからブロックリストのエントリやメモが表示されることはありません。

<Warning>
  独自のプロダクトでCheckoutまたはポータルのエラーを表示する場合も、この動作を維持してください。`PAYMENT_NOT_PERMITTED`と`PORTAL_ACTION_NOT_PERMITTED`には一般的なメッセージを表示します。ブロックされていることを明らかにすると、悪意のあるユーザーに別のメールアドレスを試すよう促してしまいます。
</Warning>

## APIを使用する

Blocklist APIを使用すると、チャージバックが発生した場合などに、独自のツールから顧客をブロックできます。秘密の[API key](/api-reference/introduction)が必要です。どのキーでもエントリの一覧表示とメモの読み取りができます。**write access**が有効なキーでは、ブロック、ブロック解除、メモの管理ができます。ダッシュボードでもチームロールに同じ区分が適用されます。**Viewer**ロールはリストを読み取り、**Editor**ロールは変更を行います。

| Method   | Endpoint                                          | Purpose                           |
| -------- | ------------------------------------------------- | --------------------------------- |
| `GET`    | `/blocklist/customers`                            | フィルターと`total`件数を含む、ブロックされた顧客の一覧表示 |
| `POST`   | `/blocklist/customers`                            | customer IDまたはメールアドレスで顧客をブロック     |
| `GET`    | `/blocklist/customers/{entry_id}`                 | メモとともにエントリを取得                     |
| `DELETE` | `/blocklist/customers/{entry_id}`                 | 顧客のブロックを解除                        |
| `POST`   | `/blocklist/customers/{entry_id}/notes`           | メモを追加                             |
| `PATCH`  | `/blocklist/customers/{entry_id}/notes/{note_id}` | メモを更新                             |

### 顧客をブロックする

リクエストボディのトップレベルに`customer_id`または`email`のいずれかを指定します。`reason`は任意で、エントリのページに表示されます。

<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`                 | 送信したcustomer IDまたはメールアドレス。                                                                                  |
| `source`                     | ブロックの作成元：`blocklist_page`、`customer_page`、`payment_page`、`dispute_page`、または`api`。API keyの場合は常に`api`が記録されます。 |
| `blocked_by_email`           | ブロックを追加したダッシュボードユーザー。API keyの場合は`null`。                                                                     |
| `cancelled_subscription_ids` | この呼び出しによってキャンセルされたサブスクリプション。                                                                                |
| `remaining_subscription_ids` | キャンセルに失敗したか、呼び出しによるキャンセル数が上限の25件に達したため、引き続き有効なサブスクリプション。                                                    |
| `subscriptions_swept`        | 有効なサブスクリプションが残っている場合は`false`。`true`になるまで呼び出しを繰り返します。ブロック自体はすでに有効です。                                         |

<Note>
  すでにブロックされている顧客をブロックすると、HTTP `409`と`CUSTOMER_ALREADY_BLOCKED`が返されます。ただし、サブスクリプションのキャンセルがまだ完了していない場合は、代わりにそのキャンセルが続行されます。
</Note>

### 顧客がブロックされているか確認する

[Get Customer Detail](/api-reference/customers/get-customers-1)は、2つの追加フィールドを返します。`blocked_at`は有効なブロックが追加された時刻（顧客がブロックされていない場合は`null`）、`blocklist_entry_id`はそのブロックの元になったエントリです。[List Customers](/api-reference/customers/get-customers) endpointでは、どちらも空のままです。

### 顧客のブロックを解除する

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

endpointは、成功時にHTTP `204`を返します。ブロックを解除するとCheckoutとポータルでの書き込みが復元されますが、サブスクリプションは再開されません。

## ベストプラクティス

* **理由を記録する。** ブロック時に短い理由を記録し、その後に発生した事象をメモに残しておくと、ダッシュボードを離れることなくサポートチームが経緯を把握できます。
* **チャージバック後にブロックする。** disputeまたは支払いから顧客を開いてそこでブロックするか、`dispute.opened` webhookと`POST /blocklist/customers`を使って自動化します。[Disputes](/features/transactions/disputes)を参照してください。
* **`subscriptions_swept`を確認する。** APIでブロックする場合は、レスポンスが`true`を返すまで呼び出しを繰り返し、有効なサブスクリプションが残らないようにします。
* **返金は別途行う。** ブロックで停止されるのは今後の購入のみです。顧客に返金する必要がある場合は、通常どおり支払いを返金してください。
* **リストを確認する。** 問題が解決した顧客のブロックを解除します。ブロック解除は即時に反映され、履歴も保持されます。

## 関連情報

<CardGroup cols={2}>
  <Card title="Customer Management" icon="user-group" href="/features/customers">
    顧客を検索し、詳細ページを開いて、サブスクリプションを管理します。
  </Card>

  <Card title="Customer Portal" icon="id-card" href="/features/customer-portal">
    顧客がポータルで実行できること、できないことを説明します。
  </Card>

  <Card title="Disputes" icon="circle-exclamation" href="/features/transactions/disputes">
    チャージバックに対応し、ブロックが妥当となるタイミングを判断します。
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/error-codes">
    `PAYMENT_NOT_PERMITTED`と`PORTAL_ACTION_NOT_PERMITTED`の意味を説明します。
  </Card>
</CardGroup>