ツールキットの CSV リファレンス
ベストプラクティスに従い、コーディング不要の Billing ツールキットを使用して、サブスクリプションの移行を成功させましょう。
このガイドを使用して、Billing 移行ツールキットで CSV ファイルを指定できます。以下の例では、すべてのタイムスタンプが Unix EPOCH 形式です。Stripe では、テスト環境で使用できるテスト用の顧客 ID と価格 ID も用意しています。
CSV の前提条件![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
CSV ファイルを作成またはダウンロードする前に、以下を把握していることを確認してください。
Customer オブジェクト | すべての顧客は、デフォルトの支払い方法を登録しておく必要があります。デフォルトの支払い方法がない場合、今後のサブスクリプションの支払いに失敗します。データの移行後にデフォルトの支払い方法が顧客に設定されていない場合、以下の 2 つのオプションを利用できます。
|
税金の自動計算 | Stripe Tax を利用する場合 (税金の自動計算を true に設定している場合)、国別の住所または郵便番号 (またはその両方) がすべての顧客に設定されている必要があります。Stripe では、指定されたサブスクリプションの税金の計算にこの情報が必要となります。 |
collection_method | サブスクリプションに send_ の支払い方法を使用する場合、以下を実行してください。
|
日付 |
|
クーポン |
|
Stripe 内での移行 | ユーザーは、Stripe のアカウント内でサブスクリプションを移行できます。顧客 ID と価格 ID (およびクーポン ID と税金 ID を使用している場合はその両方) を、移行元ではなく、移行先の Stripe アカウントに関連付けられたテンプレートに入力する必要があります。移行元のアカウントに関連付けられた ID を入力すると、移行ツールでエラーが発生します。 |
移行のユースケース![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
該当する場合は、次の移行のユースケースをお客様独自の移行に適用できます。
- さまざまな料金体系モデルのサブスクリプションを移行する
- さまざまなタイプの支払い回収方法でサブスクリプションを移行する
- サブスクリプションサイクルのさまざまな段階でサブスクリプションを移行する
- 税金が発生するサブスクリプションを移行する
- 割引のあるサブスクリプションを移行する
- Stripeアカウント内のサブスクリプションを移行する
- 複数のフェーズがあるサブスクリプションを移行する
Stripe が提供する任意の CSV テンプレート (基本、複数価格アイテム、単発価格) を必要に応じて以下の例と組み合わせることができます。
さまざまな料金体系モデルのサブスクリプションを移行する![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
月額 100 USD の基本プランや、月額 200 USD の高度なプランなどの定額の料金体系のサブスクリプションを移行できます。これらのサブスクリプションには、1 つ以上のラインアイテムを設定できます。
例 1 (基本): 2024 年 1 月 1 日から開始される、数量 2 の基本的な 100 USD の月次サブスクリプションを移行します。このサブスクリプションは、デフォルトの支払い方法を使用して自動的に請求されます。
属性` | customer (必須) | start_date (必須) | price (必須) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
フィールド | cus_xxxx1 | 1704067200 | price_xxx1 | 2 | subscription_1 | none | charge_automatically |
例 2 (複数価格のアイテム): 2024 年 1 月 1 日に開始される以下のサブスクリプションを移行し、デフォルトの支払い方法を使用して自動的に請求されるようにします。
- 数量 2 の基本的な 100 USD の月次サブスクリプション
- 数量 1 の高度な 200 USD の月次サブスクリプション
属性` | customer (必須) | start_date (必須) | items.0.price (必須) | items.0.quantity | items.1.price | items.1.quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency | |
フィールド | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | price_xxx2 | subscription_1 | none | charge_automatically |
例 3 (基本): 2024 年 1 月 1 日に開始される以下のサブスクリプションを移行し、デフォルトの支払い方法を使用して自動的に請求されるようにします。
- 数量 2 の基本的な 100 USD の月次サブスクリプション
- 20 USD の単発の請求書の追加手数料
属性` | customer (必須) | start_date (必須) | price (必須) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
フィールド | cus_xxxx1 | 1704067200 | price_xxx1 | 2 | subscription_1 | none | charge_automatically | 50 | prod_xxx1 | usd |
固定価格の金額がない場合には、単発の価格を使用してサブスクリプションを移行することもできます。
例 4 (単発の価格): 2024 年 1 月 1 日に開始される以下のサブスクリプションを移行し、デフォルトの支払い方法を使用して自動的に請求されるようにします。
- 数量 1 の 153 USD の単発の月次サブスクリプション
属性` | customer (必須) | start_date (必須) | adhoc_items.0.amount (必須) | adhoc_items.0.product | adhoc_items.0.interval | adhoc_items.0.currency | adhoc_items.0.quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
フィールド | cus_xxxx1 | 1704067200 | price_xxx1 | prod_xxx1 | 1 | subscription_1 | none | charge_automatically |
さまざまなタイプの支払い回収方法でサブスクリプションを移行する![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
移行したサブスクリプションの支払いは、保存されているデフォルトの支払い方法を使用して自動的に回収するか、顧客が期日までに支払うことができる請求書を送信して回収できます。
例 1 (基本): 2024 年 1 月 1 日から開始される、数量 1 の年間 500 USD のサブスクリプションを移行し、デフォルトの支払い方法を使用して自動的に請求されるようにします。
属性` | customer (必須) | start_date (必須) | price (必須) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
フィールド | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | none | charge_automatically |
例 2 (基本): 2024 年 1 月 1 日から開始される、数量 1 の年間 500 USD のサブスクリプションを移行します。このサブスクリプションは、顧客に送信される請求書を使用して請求され、期日は 30 日です。
属性` | customer (必須) | start_date (必須) | price (必須) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
フィールド | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | none | send_invoice | 30 |
サブスクリプションサイクルのさまざまな段階でサブスクリプションを移行する![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
例 1 (基本): 更新が必要なサブスクリプションを移行します。たとえば、更新日が 2024 年 1 月 1 日の 100 USD の月次サブスクリプションを移行します。このサブスクリプションは毎月 1 日に更新されます。
start_
を現在の更新日に設定することで、サブスクリプションが直ちに請求されるようになります。date billing_
を次回の更新サイクル日に設定します。cycle_ anchor proration_
をbehavior none
に設定します。
属性` | customer (必須) | start_date (必須) | price (必須) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
フィールド | cus_xxxx1 | 1704067200 | price_xxx1 | subscription_1 | 1706745600 | none | charge_automatically |
例 2 (基本): 請求サイクルの途中の有料のサブスクリプションを移行します。たとえば、元の開始日が 12 月 25 日の 100 USD の月次サブスクリプションを移行します。移行日は 1 月 1 日で、このサブスクリプションは毎月 25 日に更新されます。
backdate_
をサブスクリプションの元の開始日に設定します。start_ date billing_
を次回の更新日に設定します。cycle_ anchor start_
に移行日を設定します。date proration_
をbehavior none
に設定すると、顧客に再度請求することを避け、次回の請求サイクルまでサブスクリプションを予定を設定済みの状態に保つことができます。
属性` | customer (必須) | start_date (必須) | price (必須) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
フィールド | cus_xxxx1 | 1704067200 | price_xxx1 | subscription_1 | 1706140800 | none | charge_automatically | 1703462400 |
例 3 (基本): トライアル期間があるサブスクリプションを移行します。たとえば、2024 年 1 月 1 日に開始される基本的な 100 USD の月次サブスクリプションを移行します。このサブスクリプションは 2024 年 1 月 31 日までトライアル中になります。トライアルが終了すると、このサブスクリプションはデフォルトの支払い方法を使用して自動的に請求されます。
属性` | customer (必須) | start_date (必須) | price (必須) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
フィールド | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | 1706659200 | none | charge_automatically | 1703462400 |
例 4 (基本): 期日を過ぎたサブスクリプションを移行します。たとえば、最終サイクル開始日が 12 月 25 日で、まだ支払われていない 100 USD の月次サブスクリプションを移行します。1 月 1 日に開始されるサイクルの途中でこれを移行し、更新日を毎月 25 日にします。これにより、1 月 1 日から 1 月 25 日までの比例配分を適用した請求書が作成され、Stripe が支払いの回収を試行できます。
有効なサイクル内にあり、以前のシステムでまだ支払われていないサブスクリプションを移行するには、proration_
を create_
に設定し、すぐに請求書を作成して支払いを回収します。これにより、支払いがまだ未払いの場合、サブスクリプションは Stripe の督促フローにも組み込まれます。
属性` | customer (必須) | start_date (必須) | price (必須) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
フィールド | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | 1706140800 | create_prorations | charge_automatically | 1703462400 |
例 5: サイクルの終了時にキャンセルする必要があるサブスクリプションを移行します。移行後、移行のタイミング (サイクルの途中または更新時) に基づいて、これらのサブスクリプションに請求するかどうかを選択できます。
これらはその期間の終了時にキャンセルされます。たとえば、2024 年 1 月 1 日に開始される基本的な 100 USD の月次サブスクリプションを移行します。このサブスクリプションは 2024 年 1 月 31 日に自動的にキャンセルされます。
属性` | customer (必須) | start_date (必須) | price (必須) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
フィールド | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | 1706140800 | none | charge_automatically | 1703462400 | TRUE |
税金が発生するサブスクリプションを移行する![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
例 1 (基本): サブスクリプションを移行し、Stripe Taxを有効にして税金を自動計算します。たとえば、2024 年 1 月 1 日に開始される 100 USD の月次サブスクリプションを移行し、Stripe Tax を有効にして税金を自動計算します。
移行ツールキットは、事前に Stripe Tax を有効にしたかどうか、および税金を自動計算するために必要なフィールドを顧客が入力したかどうかを検証します。移行の前に、顧客が必要な情報を提供していることを確認します。
属性` | customer (必須) | start_date (必須) | price (必須) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
フィールド | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | TRUE | none | charge_automatically |
例 2 (基本): 手動税率を使用して、サブスクリプションを移行して税金を計算します。たとえば、2024 年 1 月 1 日に開始される基本的な $100 の月次サブスクリプションを移行し、手動税率を使用して 10% の税金を適用します。
- ダッシュボード (商品カタログ > クーポン) で 10% の手動税率を作成します。
- 移行の CSV テンプレートで税率 ID を使用します。
属性` | customer (必須) | start_date (必須) | price (必須) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
フィールド | cus_xxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | FALSE | 1706140800 | none | charge_automatically | txr_xxx1 |
例 3 (基本): Avalara や Verex などの外部の税金プロバイダを使用する場合:
税金がすでに計算されている移行済みのサブスクリプションでは、CSV で automatic_
と default_
の両方を空白のままにします。
サブスクリプションが移行されて本番環境になると、Billing の実装で新しいサブスクリプションに設定した税金の実装ワークフローが自動的に適用されます。
割引があるサブスクリプションを移行する![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
現在、移行ツールキットは 1 つのサブスクリプションにつき 1 つのクーポンのみをサポートします。
例 1 (基本): 移行後に適用される割引付きのサブスクリプションを移行できます。たとえば、10% の永久割引が適用される、2024 年 1 月 1 日開始の $100 の月次サブスクリプションを移行するには、以下のようにします。
- ダッシュボードで 10% のクーポンを作成します 商品カタログ > クーポン)。
- 移行の CSV ファイルでクーポン名を使用します。
属性` | customer (必須) | start_date (必須) | price (必須) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
フィールド | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | sample_coupon | none | charge_automatically |
Stripe アカウント内でサブスクリプションを移行する![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
サブスクリプションを特定の Stripe アカウントから別のアカウントに移行する際の手順は、サードパーティーシステムから移行する際の手順と同じものです。Billing 移行ツールキットを使用してサブスクリプションを移行します。 CSV ファイルのサブスクリプションデータを、以前の Stripe アカウントからエクスポートする必要があります。
例 1 (基本): Stripe 内での移行のための移行 CSV を作成するには、次のようにします。
- ダッシュボードを使用して以前の Stripe アカウントからサブスクリプションをエクスポートします。
- 新旧の Stripe アカウント間のフィールドのマッピングには、以下の CSV の例を参考にしてください。
属性` | customer (必須) | start_date (必須) | price (必須) | quantity | metadata.old_Stripe_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end |
フィールド | エクスポートフィールド: 顧客 ID (以前のアカウントのエクスポートからのもの) | エクスポートフィールド: 現在の期間終了 UTC (以前のアカウントのエクスポートからのもの) | 新しいアカウントのそれぞれの価格 ID | エクスポートフィールド: 数量 (以前のアカウントのエクスポートからのもの) | エクスポートフィールド: id (以前のアカウントのエクスポートからのもの) | 新しいアカウントで Stripe Tax を使用する場合は TRUE、それ以外の場合は FALSE | 新しいアカウントでの将来の請求日 | 新しいアカウントのそれぞれのクーポン (ある場合) | 新しいアカウントでの各トライアル (ある場合) | 比例配分された請求書の場合は create_ 、それ以外の場合は none | charge_ または send_ | 新しいアカウントの各税率 (ある場合) | エクスポートフィールド: 開始日 UTC (以前のアカウントのエクスポートからのもの) | 回収方法として send_ を使用する場合に指定 | サブスクリプションが期間の終了時にキャンセル予定であるかどうかを指定する |
複数のフェーズでサブスクリプションを移行する![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
移行ツールキットは、サブスクリプションに複数のフェーズを直接追加することをサポートしていません。以下のアプローチをお勧めします。
- 移行ツールキットを使用して、サブスクリプションの初期フェーズを移行します。
- 移行後に、移行後のサブスクリプションスケジュールにその他のフェーズを追加します。これを行うには、更新エンドポイントを呼び出すか、Stripe のサブスクリプションダッシュボードを使用します。
- 移行の
start_
を調整して、予定を設定済みのステータス変更から本番環境のステータス変更までに十分な時間を確保します。これにより、サブスクリプションを本番環境に移行する前にフェーズを更新できます。date
CSV 仕様 の詳細![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
属性 | タイプ | 説明 |
---|---|---|
customer (必須) | Stripe 顧客 ID | サブスクリプションを作成する顧客の ID。 |
start_ (必須) | エポックの Unix 形式のタイムスタンプ | サブスクリプションを作成するタイミングを決定します。 24 時間 (以上) 先の値を入力する必要があります。テスト環境では、これを 1 時間後に設定できます。 |
price (必須) | Stripe 価格 ID | 継続価格にする必要があります。複数のアイテムを移行する場合は、代わりに items. 形式を使用します。adhoc_ を使用すると、単発の価格にも対応できます。 |
quantity | 数値 | サブスクリプションの数量を決定します。デフォルトでは、各サブスクリプションは 1 つの商品に対するものですが、Stripe では 1 つのアイテムの複数の数量に対するサブスクリプションに顧客を登録できます。 |
items. (必須) | Stripe 価格 ID | Price オブジェクトの ID。継続価格にする必要があります。 |
items. | 数値 | サブスクリプションの数量を決定します。デフォルトでは、各サブスクリプションは 1 つの商品に対するものですが、Stripe では 1 つのアイテムの複数の数量に対するサブスクリプションに顧客を登録できます。 |
adhoc_ (必須) | 整数 | セント単位の正の整数 (無料の場合は 0)。詳細については、サブスクリプションの作成をご覧ください。 |
adhoc_ (必須) | Stripe プロダクト ID | 単発の価格に属する商品の ID。 |
adhoc_ (必須) | day 、week 、month 、または year | 請求の頻度。 |
adhoc_ (必須) | 文字列 | サポートされている通貨の小文字 3 文字の ISO 通貨コード。 |
adhoc_ | 数値 | サブスクリプションの数量を決定します。デフォルトでは、各サブスクリプションは 1 つの商品に対するものですが、Stripe では 1 つのアイテムの複数の数量に対するサブスクリプションに顧客を登録できます。 |
metadata_ | 文字列 | Stripe 内での移行を行う場合は、internal:Stripe と入力します。 |
metadata_ | 文字列 | 以下のキーと値のペアをオブジェクトに関連付けます。これは、オブジェクトに関する追加情報を構造化された形式で格納するのに便利です。 |
automatic_ | ブール値 | Stripe Tax による税金の自動計算設定を使用するには、true を指定します。 |
coupon | Stripe クーポン ID | このサブスクリプションに適用するクーポンの ID。 |
trial_ | タイムスタンプ | フェーズを開始日から trial_ 日付までトライアルに設定します。サイクル/フェーズの終了日より前の値を指定する必要があり、トライアルと組み合わせることはできません。 |
proration_ | create_ または none | 移行後にサブスクリプションが比例配分を作成するかどうかを決定します。デフォルト値は create_ です。 |
collection_ | charge_ または send_ | 自動的に請求する場合、 Stripe は各請求サイクルの終了時に、顧客に関連付けられたデフォルトのソースを使用して、基になるサブスクリプションの支払いを試みます。デフォルト値は charge_ です。請求書を送信する場合、 Stripe は顧客に支払い手順を記載した請求書をメールで送信し、サブスクリプションを有効としてマークします。 send_ を使用している場合は、days_ を設定する必要があります。 |
default_ | Stripe Tax の ID | サブスクリプションの default_ を設定します。これにより、このフェーズ中にサブスクリプションによって発行された請求書の default_ も決定されます。この値は、automatic_ と互換性がありません。 |
backdate_ | エポックの Unix 形式のタイムスタンプ | 作成されたサブスクリプションの start_ を決定します。これは過去の日付でなければなりません。設定されている場合、proration_ には none を指定する必要があります。これにより、backdate_ から実際の start_ までの比例配分を適用した請求書が作成されなくなります。詳細については、請求を行わずに遡及適用するをご覧ください。 |
billing_ | タイムスタンプ | 顧客にサブスクリプションを請求する将来の日付を決定します。 |
days_ | 整数 | 請求書の作成日から期日までの日数。これは必須であり、collection_ が send_ に設定された請求書にのみ有効です。 |
cancel_ | ブール値 | 期間の終了時にサブスクリプションをキャンセルするには、true を指定します。 |