# アカウントオブジェクトを使用して顧客を表す

Customers API の代わりに Accounts v2 API を使用して顧客を管理します。

Accounts v2 API は*構成* (Account configurations represent role-based functionality that you can enable for accounts, such as merchant, customer, or recipient)を使用して、`Account` オブジェクトの機能を有効にします。v2 API を使用する場合、`Account` オブジェクトに[顧客構成](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer)を割り当てることで、`Customer` オブジェクトではなく `Account` オブジェクトを使用して顧客を表すことができます。`customer` パラメーターの引数として `Customer` ID を受け付けるリクエストでは、代わりに `customer_account` パラメーターの引数として `Account` ID を指定します。

次の例では、`Account` を `customer` 構成で作成し、`customer` 構成の一部である共通の `automatic_indirect_tax` ケイパビリティをリクエストしています。ケイパビリティのリクエストは任意で、`configuration.customer` を指定するだけで構成を追加できます。

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: $latestPreviewApiVersion" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "identity": {
        "country": "us",
        "individual": {
            "given_name": "Jenny Rosen"
        }
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        }
    },
    "include": [
        "configuration.customer",
        "identity"
    ]
  }'
```

Accounts v2 API を有効にすると、Checkout などの Stripe がホストする連携では、`Customer` オブジェクトではなく、`customer` 構成を持つ `Accounts` が作成されます。コードが `Customer` オブジェクトを参照している場合は、代わりに顧客向けに構成された `Account` オブジェクトを参照するよう更新することをお勧めします。

| 目的       | v1 リファレンス                                                                            | v2 リファレンス                                                                                                                                                                                                                                                                                                                                          |
| -------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 顧客リファレンス | `customer`                                                                           | `customer_account`                                                                                                                                                                                                                                                                                                                                 |
| 顧客 ID    | `cus_xxxxx`                                                                          | `acct_xxxxx`                                                                                                                                                                                                                                                                                                                                       |
| 請求先住所の設定 | [address](https://docs.stripe.com/api/customers/create.md#create_customer-address)   | - 法人タイプが `individual` の場合は [identity.individual.address](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-identity-individual-address)。
  - [identity.business_details.address](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-identity-business_details-address) (法人タイプが `individual` 以外の場合)。 |
| 配送先住所の設定 | [shipping](https://docs.stripe.com/api/customers/create.md#create_customer-shipping) | [configuration.customer.shipping](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-shipping)                                                                                                                                                                                                       |

## 顧客としてアカウントを提供する

`Subscriptions` や `SetupIntents` などの API リクエストでは、顧客を指定する必要があります。これらのリクエストでは、`customer` または `customer_account` パラメーターを受け付けます。次の例では、サブスクリプションを作成し、`Account` ID を `customer_account` として渡して顧客を指定しています。

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: $latestPreviewApiVersion" \
  -d customer_account=acct_xxxxx \
  -d "items[0][price]=price_CBb6IXqvTLXp3f" \
  -d "items[0][quantity]=5"
```

## Customers v1 の連携機能における参照アカウント

`customer_account` を指定するリクエストは `customer` と`customer_account` の両プロパティを、対応する形式の値で返します。これにより既存の Billing および Payments の連携機能との互換性が維持されます。

```javascript
{
  "id": "sub_1Mow234",
  .
  .
  .
  "customer": "cus_xxxxx",
  "customer_account": "acct_xxxxx"
}
```

また、`/v1/customers` エンドポイントを使用して、顧客が設定したアカウントの取得または更新ができます。

```curl
curl -X POST https://api.stripe.com/v1/customers/acct_1234 \
  -u "<<YOUR_SECRET_KEY>>:"
```

## Accounts v2 Webhook

Accounts v2 の Webhook は、[シンイベント](https://docs.stripe.com/event-destinations.md#thin-events)を送信します。

| アクション          | v1 イベント                          | v2 イベント                                                                                                                           |
| -------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| 顧客の作成          | `customer.created`               | Accounts v2 は、アカウントの作成と顧客の設定を示す個別のイベントを送信します。
  - `v2.core.account.created`
  - `v2.core.account[configuration.customer].updated` |
| 請求先住所の更新       | `customer.updated`               | `v2.core.account[identity].updated`                                                                                               |
| サブスクリプションアクション | `customer.subscription.[action]` | 該当なし: v1 イベントを使用してください                                                                                                            |
| 顧客の削除          | `customer.deleted`               | `v2.core.account.closed`                                                                                                          |

## 顧客請求書プロパティ

| データ値           | Customers v1 プロパティ                        | Accounts v2 プロパティ                                                                                                                                                                                 |
| -------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 顧客のクレジット残高     | `invoice_credit_balance`                  | 該当なし: [/v1/customers パスで Accounts v2 ID を参照する](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md#reference-accounts-v2-in-v1-customers-path)をご覧ください                                |
| 顧客請求書プレフィックス   | `invoice_prefix`                          | [configuration.customer.billing.invoice.prefix](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-billing-invoice-prefix)                          |
| カスタム設定         | `invoice_settings.custom_fields`          | [configuration.customer.billing.invoice.custom_fields](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-billing-invoice-custom_fields)            |
| デフォルトの決済手段     | `invoice_settings.default_payment_method` | [configuration.customer.billing.default_payment_method](https://docs.stripe.com/api/v2/core/accounts/update.md#v2_update_accounts-response-configuration-customer-billing-default_payment_method) |
| 請求書のフッター       | `invoice_settings.footer`                 | [configuration.customer.billing.invoice.footer](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-billing-invoice-footer)                          |
| 請求書レンダリングオプション | `invoice_settings.rendering_options`      | [configuration.customer.billing.invoice.rendering.template](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-customer-billing-invoice-rendering-template)   |

## Customers エンドポイントで Account ID を参照する

Accounts v2 API には、すべての顧客機能に対応するエンドポイントがあるわけではありません。`Account` オブジェクトに対して次のアクションを実行するには、`v1/customers` エンドポイントを使用し、パスパラメーターとして `Account` ID (`acct_xxxxx`) を渡します。

| ユースケース                                                                                                                                                                                                                          | アカウント ID を持つ v1 エンドポイント                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 現金残高の管理                                                                                                                                                                                                                         | - `v1/customers/acct_xxxxx/cash_balances`
  - `v1/customers/acct_xxxxx/cash_balances/:id`                                                                                                                                                                                                                  |
| 現金残高取引の管理                                                                                                                                                                                                                       | - `GET v1/customers/acct_xxxxx/cash_balance_transactions`
  - `GET v1/customers/acct_xxxxx/cash_balance_transactions/:id`
  - `POST v1/test_helpers/customers/acct_xxxxx/fund_cash_balance`
  - `POST v1/customers/acct_xxxxx/funding_instructions`
  - `GET v1/customers/acct_xxxxx/funding_instructions` |
| 請求書のクレジット残高の管理

  `Account` オブジェクトでは、アカウントの直近で確定した請求書の [ending_balance](https://docs.stripe.com/api/invoices/object.md?api-version=preview#invoice_object-ending_balance) は、`Customer` オブジェクトの `invoice_credit_balance` に対応します。 | - `POST v1/customers/acct_xxxxx/balance_transactions`
  - `POST v1/customers/acct_xxxxx/balance_transactions/:id`
  - `GET v1/customers/acct_xxxxx/balance_transactions/:id`
  - `GET v1/customers/acct_xxxxx/balance_transactions`                                                                        |

## Customer と Account オブジェクトのプロパティマップ

次の表は、`Customer` オブジェクトのプロパティが、顧客向けに構成された `Account` オブジェクトのプロパティにどのように対応するかを示しています。特に記載がない限り、Stripe は既存の `Customer` に対応する `Account` を生成する際に、対応する値をコピーします。

マッピングされた値は同期されたまま維持されます。たとえば、`Account` に `identity.country` を設定した場合、その `Account` ID を `customer_account` として v1 エンドポイントに渡すと、返される `country` には同じ値が含まれます。

| Customers v1 プロパティ       | Accounts v2 プロパティ                                                                 | 備考                                                                                                                                                                                                                                                                   |
| ------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address`                | {all properties}                                                                  | `identity.business_details.address` または `identity.individual.address`                                                                                                                                                                                                | Stripe が v1 `Customer` を v2 `Account` に関連付ける場合、`address` は検証に合格した場合にのみ含まれます。`address.country` (v1 では文字列、v2 では列挙型) は、大文字と小文字、および特殊文字を無視して、有効な列挙値または国名のいずれかに一致する場合にのみ含まれます。 |
| `country`                | `identity.country`                                                                | Stripe が v1 `Customer` を v2 `Account` に関連付ける場合、`address.country` (文字列) は、大文字と小文字、および特殊文字を無視して、有効な列挙値または国名のいずれかに一致する場合にのみ、`identity.country` (列挙型) にコピーされます。                                                                                                          |
| `business_name`          | `identity.business_details.registered_name`                                       |                                                                                                                                                                                                                                                                      |
| `created`                | {not mapped}                                                                      | Stripe が v1 `Customer` を v2 `Account` に関連付ける場合、`Account` の `created` プロパティには、元の `Customer` ではなく、`Account` が作成された時点のタイムスタンプが反映されます。                                                                                                                                   |
| `currency`               | {not mapped}                                                                      | v2 `Account` の `defaults.currency` プロパティは、`customer` 構成には適用されません。                                                                                                                                                                                                    |
| `customer_account`       | `id`                                                                              | Stripe が v1 `Customer` を v2 `Account` に関連付けると、`Customer` の `customer_account` プロパティにその `Account` の ID が含まれます。`Customer` の ID は `Account` では使用できません。顧客を表す v2 `Accounts` を作成するユーザーは、v1 `Customer` ID を使用する必要はありません。                                                    |
| `description`            | {not mapped}                                                                      | v1 `Customer` の `description` は、v2 `Account` では使用できません。ただし、Dashboard の顧客詳細ページには表示されます (読み取り専用)。                                                                                                                                                                      |
| `email`                  | `contact_email`                                                                   |                                                                                                                                                                                                                                                                      |
| `id`                     | {not mapped}                                                                      | v1 `Customer` の ID は、v2 `Account` では使用できません。顧客を表す v2 `Accounts` を作成するユーザーは、v1 `Customer` ID を使用する必要はありません。                                                                                                                                                           |
| `individual_name`        | `display_name`                                                                    | Stripe が v1 `Customer` を v2 `Account` に関連付けると、`Customer` の `name` が null の場合にのみ `individual_name` がコピーされます。                                                                                                                                                          |
| `invoice_prefix`         | `configuration.customer.billing.invoice.prefix`                                   |                                                                                                                                                                                                                                                                      |
| `invoice_settings`       | `custom_fields`                                                                   | `configuration.customer.billing.invoice.custom_fields`                                                                                                                                                                                                               | `Account` 配列は 4 要素に制限されています。                                                                                                                                              |
| `default_payment_method` | `configuration.customer.billing.invoice.default_payment_method`                   |                                                                                                                                                                                                                                                                      |
| `footer`                 | `configuration.customer.billing.invoice.footer`                                   |                                                                                                                                                                                                                                                                      |
| `rendering_options`      | `configuration.customer.billing.invoice.rendering`                                | Stripe が v1 `Customer` を v2 `Account` に関連付けると、`invoice_settings.rendering_options.amount_tax_display` (string) は、列挙値 (`include_inclusive_tax` または `exclude_tax`) に一致する場合にのみ `configuration.customer.billing.invoice.rendering.amount_tax_display` (enum) にコピーされます。   |
| `livemode`               | `livemode`                                                                        |                                                                                                                                                                                                                                                                      |
| `metadata`               | `metadata`                                                                        |                                                                                                                                                                                                                                                                      |
| `name`                   | `display_name`                                                                    | Stripe が v1 `Customer` を v2 `Account` に関連付けると、`name` が null の場合、`Customer` の `individual_name` が `display_name` にコピーされます。                                                                                                                                            |
| `next_invoice_sequence`  | `configuration.customer.billing.invoice.next_sequence`                            |                                                                                                                                                                                                                                                                      |
| `phone`                  | `identity.business_details.phone or identity.individual.phone`                    |                                                                                                                                                                                                                                                                      |
| `preferred_locales`      | `defaults.locales`                                                                | `Customer` プロパティ `preferred_locales` は、null を許容する文字列の配列です。一方、`Account` プロパティ `defaults.locales` は、null を許容する列挙型の配列です。Stripe が v1 の `Customer` を v2 の `Account` に関連付ける場合、指定された `preferred_locales` の文字列は、大文字と小文字、および特殊文字を無視して `defaults.locales` の列挙値と一致する場合にのみ含まれます。 |
| `shipping`               | `configuration.customer.shipping`                                                 |                                                                                                                                                                                                                                                                      |
| `subscriptions`          | {not mapped}                                                                      | v2 の `Account` オブジェクトには、サブスクリプションの配列は含まれません。顧客のサブスクリプションを取得するには、Subscriptions API を使用し、`customer` または `customer_account` で絞り込みます。                                                                                                                                    |
| `tax`                    | `automatic_tax`                                                                   | `configuration.customer.capabilities.automatic_indirect_tax.status` {value not synchronized}                                                                                                                                                                         | `Account` プロパティは、Automatic Indirect Tax ケイパビリティをリクエストした後でのみ使用できます。また、`Customer` プロパティの `not_collecting` に相当する値はありません。このプロパティは、ケイパビリティのステータスのみを示します。                       |
| `ip_address`             | `configuration.customer.automatic_indirect_tax.ip_address`                        |                                                                                                                                                                                                                                                                      |
| `location`               | `configuration.customer.automatic_indirect_tax.location` {value not synchronized} | Stripe が v1 の `Customer` を v2 の `Account` に関連付ける場合でも、`tax.location` は自動的には含まれません。`configuration.customer.automatic_indirect_tax.location` を設定するには、Automatic Indirect Tax ケイパビリティをリクエストする必要があります。                                                                     |
| `provider`               | {not mapped}                                                                      | `Customer` がサードパーティーの税金プロバイダーに関連付けられている場合、Stripe はその `Customer` を `Account` に自動的には関連付けません。                                                                                                                                                                           |
| `tax_exempt`             | `configuration.customer.automatic_indirect_tax.exempt`                            |                                                                                                                                                                                                                                                                      |
| `tax_ids`                | {not mapped}                                                                      | v2 の `Account` オブジェクトには、納税者番号の配列は含まれません。顧客の納税者番号を取得するには、Tax IDs API を使用し、`owner.customer` または `owner.customer_account` で絞り込みます。                                                                                                                                      |
| `test_clock`             | `configuration.customer.test_clock`                                               |                                                                                                                                                                                                                                                                      |

## Accounts v2 プレビューを有効にする

以前は、Accounts v2 API は Connect プラットフォームでのみ利用可能でした。現在は、すべての Stripe ユーザーがプレビューで利用できます。

Accounts v2 では、Stripe 製品全体でユーザーを統一的に表現できます。決済手段の保存と継続課金の機能のみを提供する `Customer` オブジェクトの代わりに、`Account` オブジェクトを使用できます。追加機能が必要な場合は、設定を使用することで、より柔軟に対応できます。

プレビューを有効にするには、次のようにします。

1. ダッシュボードの [Account previews and features](https://dashboard.stripe.com/settings/features/product-previews) に移動します。
1. **Global Payouts の再利用可能な決済手段**のトグルを有効にします。トグルが表示されない場合は、このページの上部にあるフォームを使用してアクセスをリクエストしてください。

オプトインすると、既存の `Customer` オブジェクトは、対応する顧客設定済みの v2`Account` オブジェクトと自動的に同期されます。ダッシュボードで新しい顧客を作成すると、顧客設定済みの `Account` オブジェクトが生成され、`Customer` オブジェクトは生成されません。これらの `Accounts` は、[Customer オブジェクトを参照するほとんどの連携](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md#reference-accounts-in-customers-v1-integrations)で使用できます。

Accounts v2 プレビューを有効にすると、[Global Payouts の再利用可能な決済認証情報](https://docs.stripe.com/global-payouts/credential-reuse.md)も有効になり、Global Payouts の取引全体で決済手段を保存して再利用できるようになります。

## 制限とオプトアウト

Accounts v2 プレビューは、次の機能に対応していません。

- [顧客のクローン作成](https://docs.stripe.com/get-started/data-migrations/pan-copy-self-serve.md)
- [組織内で顧客と決済手段を共有する](https://docs.stripe.com/get-started/account/orgs/sharing/customers-payment-methods.md)
- サードパーティーの税金連携 (Stripe Tax に対応)

オプトアウトするには、[Account previews and features](https://dashboard.stripe.com/settings/features/product-previews) でトグルをオフにします。

オプトアウトしても、すでに v2`Account` オブジェクトに関連付けられている既存の `Customer` オブジェクトは元に戻りません。これらの顧客に未対応の機能が必要な場合は、その顧客用に新しい `Customer` オブジェクトを作成する必要があります。