従量課金をモデル化する

従量課金を使用したサブスクリプションのトライアル期間を使用できます。トライアル期間中に発生した使用量は、請求サイクルの終了時に顧客に対して請求される総額に含められません。トライアル期間の終了後に使用量が発生し、それが次回の請求サイクルの終了時に請求されます。

トライアル期間とサブスクリプションの詳細をご覧ください。

Webhook とトライアル

システムでトライアルステータスの変更に関連するウェブイベントの監視と処理が適切に行われていることを確認します。

トライアルが終了し、サブスクリプションが trialing から active に移行する数日前に、customer.subscription.trial_will_end イベントを受信します。このイベントを受信したら、顧客のアカウントに支払い方法の指定があり、請求の進行が可能な状態あることを確認します。必要に応じて、次回の支払いについて事前に顧客に通知します。

サブスクリプションと Webhook の詳細をご覧ください。

従量課金の場合、顧客が支払う請求書は、請求サイクル中の使用量に基づいて異なります。請求サイクルを変えると、サブスクリプション期間の終了が早まり、短縮された請求サイクル中に発生した使用量に対して顧客に請求することになります。従量課金では比例配分はサポートされていません。

キャンセルされたサブスクリプションを、再びアクティブにすることはできません。代わりに、顧客から更新された請求先情報を収集し、顧客のデフォルトの支払い方法を更新して、既存の顧客レコードから新しいサブスクリプションを作成できます。

cancel_at_period_end を使用してサブスクリプションのキャンセルをスケジュール設定した場合、cancel_at_period_end を false に更新することで、期間の終了時まではサブスクリプションをいつでも再有効化できます。最終請求書には、請求期間の終了時にサブスクリプションをキャンセルしてから計測された使用量が含まれます。

単価を適用する前に使用量を変換するには、transform_quantity オプションを使用します。これにより、報告された使用量を特定の数で割って、結果を切り上げまたは切り捨てできます。これは、個々の単価ではなく、商品のパッケージに対して価格を設定する場合に一般的に使用されます。数量の変換は、段階制料金とは互換性がありません。

たとえば、レンタカーサービスを運営しているとします。あなたは使用量を分単位の時間で報告して、レンタカーを貸し出した 1 時間ごとに顧客に請求したいと考えています。

curl https://api.stripe.com/v1/products \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d name="Car Rental Service"

次に、レンタカーサービス商品の料金を作成します。1 時間単位で 10 USD を請求し、使用時間が 1 時間に満たない場合も切り上げて 1 時間分を請求します。

curl https://api.stripe.com/v1/prices \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d nickname="Car Rental Per Hour Rate" \
  -d unit_amount=1000 \
  -d currency=usd \
  -d "recurring[interval]"=month \
  -d "recurring[usage_type]"=metered \
  -d product={{CAR_RENTAL_SERVICE_PRODUCT_ID}} \
  -d "transform_quantity[divide_by]"=60 \
  -d "transform_quantity[round]"=up

車が 150 分間レンタルされた場合、その顧客は 3 時間のレンタル (2 時間 30 分の切り上げ) に対する 30 USD を請求されます。

小数を使用する料金は、整数ではない料金の金額を作成する必要がある場合に利用できます。たとえば、クラウドストレージの SaaS ビジネスを運営している場合、1 カ月につき、1 MB あたり 0.05 セントを請求する料金を作成できます。使用量を基準にして MB の数量に 0.05 セントを乗じて、最も近い整数のセントに丸めます。

小数を使用する価格を作成するには、unit_amount ではなく、unit_amount_decimal を指定します。unit_amount_decimal を使用すると、請求通貨の補助単位で金額を設定できます。たとえば、USD で unit_amount_decimal = 105.5 と設定して 105.5 セント、(1.055 USD) を示すことができます。unit_amount_decimal では、小数点以下最大 12 桁までを使用できます。

段階制料金の使用を計画している場合は、unit_amount ではなく unit_amount_decimal を使用できます。また、unit_amount の代わりに unit_amount_decimal を使用して請求書アイテムを作成することもできます。

API レスポンスでは、オブジェクトを小数点付きの値で作成すると、整数 unit_amount フィールドには入力されません。たとえば、unit_amount_decimal = 0.05 で価格を作成すると、レスポンスには unit_amount = null と unit_amount_decimal = 0.05 が含まれます。unit_amount_decimal には整数値を渡すこともでき、その場合はレスポンスの unit_amount に入力されます。たとえば、unit_amount_decimal = 5 で価格を作成すると、レスポンスには unit_amount = 5 と unit_amount_decimal = 5.0 が含まれます。

デフォルトでは、Stripe はサブスクリプションが生成されてから 1 時間後にその請求書を確定します。この 1 時間の猶予期間中は、以前の期間の使用量を引き続き報告できます。請求書が確定すると、その請求期間の最新の数量を反映するように更新されます。

請求書の確定後に報告された使用量は、今後の請求書にはキャプチャーされません。

You can configure a longer grace period.

請求サイクル中にサブスクリプションアイテムの価格を更新できます。ただし、請求メーター価格を別の価格に切り替える場合は、以下の制限が適用されます。

• 更新後の使用分は、次回からの請求書に反映されます。変更前の使用分は請求書に反映されません。たとえば、1 月 16 日に月額のサブスクリプションを料金 A から料金 B に変更した場合、月末に生成される請求書には、1 月 16 日から 1 月 31 日までの料金 B での使用分が計上されます。
• このルールの例外として、請求しきい値を使用している場合に、しきい値のある請求書が古い料金ですでに生成されている場合があります。たとえば、上記のシナリオで、1 月 10 日に料金 A でしきい値のある請求書を生成した場合、そのしきい値のある請求書は顧客に請求されます。月末に生成される請求書では、1 月 16 日から 1 月 31 日までの使用分が料金 B で計上されます。以前に生成されたしきい値のある請求書は、この月末の請求書の使用分を埋め合わせません。
• サブスクリプションサイクルの途中で新しい請求メーター価格のサブスクリプションアイテムを追加する場合にも、同様の制限が適用されます。たとえば、1 月 16 日に料金 C の新しいサブスクリプションアイテムを追加した場合、月末に生成される請求書には、1 月 16 日から 1 月 31 日までのそのサブスクリプションアイテムの料金 C での使用分が計上されます。

サブスクリプションアイテムの価格を更新する方法を以下でご覧いただけます。

curl https://api.stripe.com/v1/subscription_items/{{SUBSCRIPTION_ITEM_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d price={{NEW_PRICE_ID}}

サブスクリプションアイテムを削除するには、以下のようにします。

curl -X DELETE https://api.stripe.com/v1/subscription_items/{{SUBSCRIPTION_ITEM_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

削除後は、そのアイテムの使用分は請求書に反映されません。

顧客のサブスクリプションを作成する前の段階で顧客の使用量を報告できます。顧客の使用量を報告した後で、backdate_start_date を使用して、最初の報告の前のサブスクリプションを作成し、使用量が次のサブスクリプション請求書に含まれるようにします。

curl -X POST https://api.stripe.com/v2/billing/meter_events \
  -H "Authorization: Bearer 
{{YOUR_API_KEY}}
" \
  -H "Stripe-Version: 2024-12-03.preview-v2" \
  --json '{
    "event_name": "alpaca_ai_tokens",
    "payload": {
        "value": "25",
        "stripe_customer_id": "{{CUSTOMER_ID}}"
    },
    "timestamp": "2024-04-01T12:00:00.000Z"
  }'

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d customer={{CUSTOMER_ID}} \
  -d "items[0][price]"={{PRICE_ID}} \
  -d backdate_start_date=1710000000