# 事前請求

事前請求を使用して、将来の複数のサービス期間分の支払いを今すぐ回収しましょう。

## まずこちらをご覧ください: エージェントスキルのインストール

Stripe では、ベストプラクティスに沿って API と連携するために、公式スキルの使用を推奨しています。詳細は以下の手順をご確認ください。

**ヒント: Fetch ツールではなく curl を使用してください。** スキルは 10 ～ 20 KB の詳細なマークダウンファイルです。Fetch ツールは内容を要約します。`curl -sL` を使うと、完全な内容を取得できます。

**`npx skills` の使用方法**: `npx` がシステムにインストールされているか確認します。`npx` が使用可能な場合は、`npx skills addhttps://docs.stripe.com --list` を実行して利用可能なスキルを一覧表示し、続いて`npx skills addhttps://docs.stripe.com --yes --skill<skill-name> <--skill other-skills>` を実行して個別のスキルをインストールします。

**`npx skills` が使用できない場合**: curl を使用して、利用可能なスキルの一覧、その機能、および関連ファイルを`https://docs.stripe.com/.well-known/skills/index.json`. から取得できます。スキルとその関連ファイルをダウンロードするには、curl を使用して`https://docs.stripe.com/.well-known/skills/<filepath>`. からダウンロードします。

この記事では、次のスキルの使用を推奨します: `stripe-best-practices`

事前請求により、複数のサービス期間について顧客に前払い請求ができます。事前請求は、サブスク作成時、または既存のサブスクへの追加時に有効にできます。

> #### 柔軟な請求モードが必要です
> 
> 事前請求には、[柔軟な請求モード](https://docs.stripe.com/billing/subscriptions/billing-mode.md)が有効になっているサブスクが必要です。柔軟な請求モードが有効になっていない場合は、[柔軟な請求モード](https://docs.stripe.com/billing/subscriptions/billing-mode.md)で手順をご確認ください。

## ユースケース

事前請求を使用すると、将来のサービス期間の支払いを前払いで回収できます。一般的なユースケースは以下のとおりです。

| ユースケース           | 説明                                                                              |
| ---------------- | ------------------------------------------------------------------------------- |
| **登録時に複数月分を前払い** | 月次サブスクリプションの顧客が登録する際に、3 カ月分を前払いで請求し、その後は通常の月次請求を再開します。                          |
| **早期更新請求**       | 更新まで 7 日を切った時点で、請求サイクルの終了を待たずに、更新の請求書を今すぐ作成して顧客に送付します。                          |
| **月次料金の年払い**     | 顧客が、基礎となる料金を年次単位に変更することなく、月次プランの 12 カ月分を 1 回の前払い請求書でまとめて支払えるようにします。             |
| **項目レベルの事前請求**   | 特定のアドオン項目を事前請求し、同じサブスクの他のアイテムは通常の月次請求を行います。                                     |
| **早期解約手数料**      | 顧客がコミット期間中に早期解約した場合、コミット終了日まで前払い請求を行い、その後サブスクリプションをキャンセルすることで、残存期間分の手数料を請求できます。 |

### 制限事項

事前請求には以下の制限があります。

- 事前請求は、[サブスクスケジュール](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md)、またはサブスクスケジュールに基づくサブスクでは使用できません。
- 事前請求では、[percent_off](https://docs.stripe.com/api/coupons/object.md#coupon_object-percent_off) と [duration](https://docs.stripe.com/api/coupons/object.md#coupon_object-duration) が `once` または `forever` に設定されたクーポンのみを使用できます。
- すべてのサブスク項目に使用量ベースの価格が設定されている場合、事前請求を有効にできません。サブスクの使用量ベースの価格には事前請求は適用されません。価格に [usage_type=metered](https://docs.stripe.com/api/prices/object.md#price_object-recurring-usage_type) が設定されている場合は、[applies_to[price]](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-billing_schedules-applies_to) を設定できません。
- サブスクのキャンセルがスケジュールされている場合、事前請求の終了日を予定されたキャンセル日より後に設定することはできません。

## 事前請求の仕組み

事前請求では、サブスクに [billing_schedules](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-billing_schedules) を使用して、前払い請求する項目と期間を設定します。`billing_schedules` を設定すると、Stripe が各請求サイクルの到来を待つのではなく、サブスク作成時または更新時に、指定されたすべての将来のサービス期間をカバーする前払い請求書を生成します。

事前請求は[項目](https://docs.stripe.com/api/subscription_items.md)レベルで適用されます。すなわち、対象に価格 ID とともに `applies_to` パラメーターを渡すことで特定の項目を事前請求するか、`applies_to` を完全に省略してサブスクで該当するすべてのライセンス価格項目を事前請求できます。従量課金制の価格は、`applies_to` の設定にかかわらず、事前請求に含まれることはありません。

[bill_until](https://docs.stripe.com/api/subscriptions/update.md?api-version=preview#update_subscription-billing_schedules-bill_until) パラメーターは、事前請求期間の終了日を制御します。これは、`duration` (例: 現在の日付から 2 カ月後) または `timestamp` (特定の Unix タイムスタンプ) として表現できます。

## 事前請求を使用するサブスクの作成

サブスク作成時に事前請求を設定するには、[billing_schedules](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-billing_schedules) を使用して事前請求する項目と期間を指定します。

- `applies_to` を使用して、価格 ID で事前請求する項目を指定します。対象となるすべての項目を事前請求するには、このパラメーターは省略できます。
- `bill_until` を使用して、事前請求の終了日を期間またはタイムスタンプとして設定します。
- `proration_behavior` を使用して、事前請求の請求書が生成されるタイミングを制御します。

事前請求の終了日を設定する場合

- 終了日は、最初の請求期間の終了日以降にする必要があります。たとえば、月次サブスクリプションの場合、終了日は請求期間の開始から 1 カ月以上先にする必要があります。
- すべての項目の合計事前請求サイクル数は 50 を超えることはできません。たとえば、2 つのアイテムがある場合、それぞれ最大 25 カ月まで事前請求を設定できます。
- 終了日を今から 5 年以上先に設定することはできません。

#### ダッシュボード

ダッシュボードで事前請求を使用してサブスクリプションを作成するには、以下のようにします。

1. [サブスクリプションのページ](https://dashboard.stripe.com/subscriptions?status=active)にアクセスしてください。
2. **+ サブスクリプションを作成**をクリックします。
3. **サブスクリプション設定** セクションで、 **前払い** を有効にします。
4. 事前請求の終了日を選択します。サブスクリプションのすべての項目は、選択した日付まで事前請求されます。
5. **詳細設定** セクションで、 **Billingモード** を **Flexible** に設定します。
6. **サブスクリプションの作成**をクリックします。

既存のサブスクリプションを更新するには、以下のようにします。

> 事前請求を有効にするには、サブスクがすでに `billing_mode=flexible` になっている必要があります。詳細については、[制限事項](https://docs.stripe.com/billing/subscriptions/prebilling.md#limitations)をご覧ください。

1. [サブスクリプションのページ](https://dashboard.stripe.com/subscriptions?status=active)にアクセスしてください。
2. 更新するサブスクリプションをクリックして、 **アクション** > **サブスクリプションの更新** を選択します。
3. **サブスクリプション設定** セクションで、 **前払い** を有効にします。
4. 事前請求の終了日を選択します。サブスクリプションのすべての項目は、選択した日付まで事前請求されます。
5. **サブスクリプションを更新** をクリックします。

#### API

### 特定項目を事前請求

サブスクの特定価格を事前請求するには、事前請求する価格 ID を含む `applies_to` 配列を渡します。

#### Accounts v2

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer_account={{CUSTOMERACCOUNT_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  --data-urlencode "items[1][price]={{PRICE_1, PRICE_2}}" \
  -d "billing_mode[type]=flexible" \
  -d "billing_schedules[0][applies_to][0][type]=price" \
  -d "billing_schedules[0][applies_to][0][price]={{PRICE_ID}}" \
  -d "billing_schedules[0][bill_until][type]=duration" \
  -d "billing_schedules[0][bill_until][duration][interval]=month" \
  -d "billing_schedules[0][bill_until][duration][interval_count]=2"
```

#### Customer v1

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  -d "items[1][price]={{PRICE_ID}}" \
  -d "billing_mode[type]=flexible" \
  -d "billing_schedules[0][applies_to][0][type]=price" \
  -d "billing_schedules[0][applies_to][0][price]={{PRICE_ID}}" \
  -d "billing_schedules[0][bill_until][type]=duration" \
  -d "billing_schedules[0][bill_until][duration][interval]=month" \
  -d "billing_schedules[0][bill_until][duration][interval_count]=2"
```

### 複数項目を事前請求

複数の項目を事前請求するには、複数のオブジェクトを `applies_to` 配列に追加します。

#### Accounts v2

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer_account={{CUSTOMERACCOUNT_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  -d "items[1][price]={{PRICE_ID}}" \
  -d "billing_mode[type]=flexible" \
  -d "billing_schedules[0][applies_to][0][type]=price" \
  -d "billing_schedules[0][applies_to][0][price]={{PRICE_ID}}" \
  -d "billing_schedules[0][applies_to][1][type]=price" \
  -d "billing_schedules[0][applies_to][1][price]={{PRICE_ID}}" \
  -d "billing_schedules[0][bill_until][type]=duration" \
  -d "billing_schedules[0][bill_until][duration][interval]=month" \
  -d "billing_schedules[0][bill_until][duration][interval_count]=2"
```

#### Customer v1

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  -d "items[1][price]={{PRICE_ID}}" \
  -d "billing_mode[type]=flexible" \
  -d "billing_schedules[0][applies_to][0][type]=price" \
  -d "billing_schedules[0][applies_to][0][price]={{PRICE_ID}}" \
  -d "billing_schedules[0][applies_to][1][type]=price" \
  -d "billing_schedules[0][applies_to][1][price]={{PRICE_ID}}" \
  -d "billing_schedules[0][bill_until][type]=duration" \
  -d "billing_schedules[0][bill_until][duration][interval]=month" \
  -d "billing_schedules[0][bill_until][duration][interval_count]=2"
```

### すべての項目を事前請求

該当するすべての項目を事前請求する場合は、`applies_to` 配列を省略できます。事前請求は、その終了日までに少なくとも 1 回サイクルがあり、ライセンス価格が設定されたサブスクのすべての項目に適用されます。

#### Accounts v2

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer_account={{CUSTOMERACCOUNT_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  -d "items[1][price]={{PRICE_ID}}" \
  -d "billing_mode[type]=flexible" \
  -d "billing_schedules[0][bill_until][type]=duration" \
  -d "billing_schedules[0][bill_until][duration][interval]=month" \
  -d "billing_schedules[0][bill_until][duration][interval_count]=2"
```

#### Customer v1

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  -d "items[1][price]={{PRICE_ID}}" \
  -d "billing_mode[type]=flexible" \
  -d "billing_schedules[0][bill_until][type]=duration" \
  -d "billing_schedules[0][bill_until][duration][interval]=month" \
  -d "billing_schedules[0][bill_until][duration][interval_count]=2"
```

### 一定期間について事前請求する

現在の日付からの指定期間について事前請求を行うには、`type` を `duration` に設定し、`interval` と `interval_count` を設定します。たとえば、2 カ月間事前請求するには、`interval` を `month` に、`interval_count` を `2` に設定します。

#### Accounts v2

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer_account={{CUSTOMERACCOUNT_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  -d "items[1][price]={{PRICE_ID}}" \
  -d "billing_mode[type]=flexible" \
  -d "billing_schedules[0][bill_until][type]=duration" \
  -d "billing_schedules[0][bill_until][duration][interval]=month" \
  -d "billing_schedules[0][bill_until][duration][interval_count]=2"
```

#### Customer v1

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  -d "items[1][price]={{PRICE_ID}}" \
  -d "billing_mode[type]=flexible" \
  -d "billing_schedules[0][bill_until][type]=duration" \
  -d "billing_schedules[0][bill_until][duration][interval]=month" \
  -d "billing_schedules[0][bill_until][duration][interval_count]=2"
```

### タイムスタンプまでに事前請求する

特定の日付まで事前請求するには、`type` を `timestamp` に設定し、`timestamp` を事前請求を終了する Unix タイムスタンプに設定します。

#### Accounts v2

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer_account={{CUSTOMERACCOUNT_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  -d "items[1][price]={{PRICE_ID}}" \
  -d "billing_mode[type]=flexible" \
  -d "billing_schedules[0][bill_until][type]=timestamp" \
  -d "billing_schedules[0][bill_until][timestamp]=1679609767"
```

#### Customer v1

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  -d "items[1][price]={{PRICE_ID}}" \
  -d "billing_mode[type]=flexible" \
  -d "billing_schedules[0][bill_until][type]=timestamp" \
  -d "billing_schedules[0][bill_until][timestamp]=1679609767"
```

### 請求書を直ちに生成

サブスクの作成または更新時に事前請求の請求書を直ちに生成するには、`proration_behavior` を `always_invoice` に設定します。

#### Accounts v2

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer_account={{CUSTOMERACCOUNT_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  -d "items[1][price]={{PRICE_ID}}" \
  -d "billing_mode[type]=flexible" \
  -d proration_behavior=always_invoice \
  -d "billing_schedules[0][bill_until][type]=timestamp" \
  -d "billing_schedules[0][bill_until][timestamp]=1679609767"
```

#### Customer v1

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  -d "items[1][price]={{PRICE_ID}}" \
  -d "billing_mode[type]=flexible" \
  -d proration_behavior=always_invoice \
  -d "billing_schedules[0][bill_until][type]=timestamp" \
  -d "billing_schedules[0][bill_until][timestamp]=1679609767"
```

### 次の請求サイクルで請求書を生成

次の自然な請求サイクル日に事前請求の請求書を生成するには、`proration_behavior` を `create_prorations` に設定します。

#### Accounts v2

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer_account={{CUSTOMERACCOUNT_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  -d "items[1][price]={{PRICE_ID}}" \
  -d "billing_mode[type]=flexible" \
  -d proration_behavior=create_prorations \
  -d "billing_schedules[0][bill_until][type]=timestamp" \
  -d "billing_schedules[0][bill_until][timestamp]=1679609767"
```

#### Customer v1

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "items[0][price]={{PRICE_ID}}" \
  -d "items[1][price]={{PRICE_ID}}" \
  -d "billing_mode[type]=flexible" \
  -d proration_behavior=create_prorations \
  -d "billing_schedules[0][bill_until][type]=timestamp" \
  -d "billing_schedules[0][bill_until][timestamp]=1679609767"
```

## 事前請求が設定された既存のサブスクの更新

既存のサブスクに事前請求を追加するには、`billing_schedules` パラメーターを使用してサブスクを更新します。サブスクの請求モードは `billing_mode=flexible` になっている必要があります。

```curl
curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "billing_schedules[0][bill_until][type]=duration" \
  -d "billing_schedules[0][bill_until][duration][interval]=month" \
  -d "billing_schedules[0][bill_until][duration][interval_count]=2"
```

## 早期解約手数料

事前請求を使用して、顧客が早期キャンセルした時に確定済みの契約の残余期間について請求します。これは、定期的 (たとえば毎月) に請求する期間固定のサブスクで一般的な方法です。

たとえば、ある顧客が月額 10 USD の 1 年契約のプランに 1 月 1 日にサインアップし、9 月 10 日にキャンセルするとします。残りの契約確定分を回収するには、最後の請求書で 12 月までの分を事前請求し、その後比例配分なしでサブスクをキャンセルします。

1. [サブスクリプションを更新](https://docs.stripe.com/api/subscriptions/update.md)して、`billing_schedules.bill_until` を確定した期間の終了日 (12 月 31 日) に設定します。
2. `proration_behavior` を `none` に設定して、[サブスクリプションをキャンセル](https://docs.stripe.com/api/subscriptions/cancel.md)します。

顧客の最終請求書には、早期キャンセル手数料として確定済みの 10 月、11 月、12 月の料金が含まれます。

このパターンは、より長期の確定済み契約 (例: 顧客が 2 年契約の 18 カ月目にキャンセルする場合) や、顧客が期間の中途でアップグレードして残りの期間分を新しい価格で前払いする早期更新のシナリオにも適用できます。

## その他の考慮事項

### 請求書生成のタイミング

事前請求の請求書は、`billing_schedules` を設定してサブスクを作成または更新したときに生成されます。正確なタイミングは `proration_behavior` の設定によって異なります。

- `always_invoice`: サブスクが作成または更新されるとすぐに、事前請求の請求書を生成、確定します。
- `create_prorations`: 次の自然な請求サイクル日に事前請求の請求書を生成します。

顧客が直ちに前払い請求書を受け取るようにする場合は、`always_invoice` を使用します。次回の請求日に顧客の通常の請求書と一緒に請求書を表示したい場合は、`create_prorations` を使用します。

### Webhook およびイベント

事前請求により、通常の請求サイクル外で請求書が生成されます。実装で関連するイベントが処理されることを確認してください。たとえば、事前請求の請求書に対して支払いが行われたときに顧客に領収書を送信したり、リトライフローで支払いの失敗を処理したりすることができます。

| イベント                            | 説明                                              | ユースケース                                   |
| ------------------------------- | ----------------------------------------------- | ---------------------------------------- |
| `invoice.created`               | Stripe が事前請求の請求書を生成したときに送信されます。                 | システムに事前請求を記録します。                         |
| `invoice.finalized`             | 請求書が確定し、支払いの準備が整ったときに送信されます。                    | 顧客への通知ワークフローをトリガーします。                    |
| `invoice.payment_succeeded`     | 事前請求の請求書に対する支払いが成功したときに送信されます。                  | 前払いされたサービス期間へのアクセス権を顧客に付与します。            |
| `invoice.payment_failed`        | 事前請求の請求書に対する支払いが失敗したときに送信されます。                  | 支払いの失敗の処理: リトライロジック、顧客への通知、またはサブスクの一時停止。 |
| `customer.subscription.updated` | サブスクが新しい `billing_schedules` 設定で更新されたときに送信されます。 | 更新されたサブスクの状態をシステムに同期します。                 |

### 事前請求用請求書のプレビュー

サブスクを作成または更新して事前請求を使用する前に、顧客の請求書をプレビューできます。API を使用して[プレビュー請求書を作成](https://docs.stripe.com/api/invoices/create_preview.md)し、`subscription_details` パラメーターに [billing_schedules](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-subscription_details-billing_schedules) を含めます。これにより、事前請求のために生成された請求書が表示されます。

### クーポンとの関係

事前請求と互換性があるのは、 `duration` が `once` または `forever` の `percent_off` クーポンのみです。`amount_off` クーポンと `duration=repeating` クーポンが `billing_schedules` が設定されたサブスクで使用されるとエラーが返されます。

## See also

- [柔軟な請求モード](https://docs.stripe.com/billing/subscriptions/billing-mode.md)
- [比例配分](https://docs.stripe.com/billing/subscriptions/prorations.md)
- [請求書のプレビュー](https://docs.stripe.com/api/invoices/create_preview.md)
- [サブスクの請求サイクル](https://docs.stripe.com/billing/subscriptions/billing-cycle.md)