# Stripe の API を使用してサブスクリプションを Stripe Billing に移行する Stripe の API を使用して既存のサブスクリプションを Stripe に移行する方法をご紹介します。 Stripe API を使用して、サードパーティー、社内のシステム、または既存の Stripe アカウントから Stripe Billing に既存の *サブスクリプション* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis)を移行する方法をご紹介します。 ## はじめに 1. [移行のステージ](https://docs.stripe.com/billing/subscriptions/migrate-subscriptions.md)を確認していない場合は、最初に確認します。 1. [Stripe Billing を設定](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md)します。この事前準備は、サブスクリプションを Stripe にインポートする前に一度だけ行う必要があり、将来の移行時に繰り返す必要はありません。 1. 現在の決済代行業者からの[PAN データのインポートをリクエストする](https://docs.stripe.com/get-started/data-migrations/pan-import.md)。 Stripe 内での移行を行う場合、すでに決済処理にStripeを使用しているため、この前提条件は必要ありません。 ## レガシーの商品と価格を管理する Stripe で引き続きサポートする必要がある*レガシー* (Technology that's no longer recommended)*料金体系モデル* (The pricing model consists of the products or services you sell, how much they cost, what currency you accept for payments, and the service period to charge (for subscriptions). To build the pricing model, you use Products—what you sell—and Prices—how much and how often to charge for your products)がある場合、`Legacy plan` などのプレースホルダー商品を作成します。次に例を示します。 ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ -d id={{NEW_PRODUCT_ID}} \ -d "name=Legacy plan" \ -d "description=Imported legacy plan from source system" \ -d "metadata[OLD_PRODUCT_ID]={{OLD_PRODUCT_ID}}" ``` レガシープランがあるサブスクリプションを更新する必要があるときは、必要に応じて `items.price_data` を使用して料金を渡します。これは、既存のレガシー価格を上書きします。詳細については、[変動料金](https://docs.stripe.com/products-prices/how-products-and-prices-work.md#variable-pricing)をご覧ください。 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer={{CUSTOMER_ID}} \ -d "items[0][price_data][currency]=USD" \ -d "items[0][price_data][product]={{PRODUCT_ID}}" \ -d "items[0][price_data][recurring][interval]=month" \ -d "items[0][price_data][recurring][interval_count]=3" \ -d "items[0][price_data][unit_amount]=1000" \ -d "items[0][quantity]=1" ``` ## サブスクリプションをインポートする 顧客をインポートし、料金体系モデルを作成したら、サブスクリプションのインポートを開始できます。サードパーティーシステムから、それらの UI や API を使用してサブスクリプションデータをエクスポートすることも可能になります。いずれかのインターフェイスでこの方法を使用できない場合は、サブスクリプションの処理業者にお問い合わせください。 サブスクリプションをインポートするには、顧客リストを使用して、顧客ごとに適切なサブスクリプションを作成します。たとえば、登録者が以前のモデルで月次の `Basic` の料金プランを利用している場合、Stripe でサブスクリプションを作成する際に、そのレベルに関連付けられた月次の継続価格を使用します。 ### ソースデータを Stripe に対応させる サブスクリプションを Stripe にインポートする前に、すべてのソースデータが Stripe が想定する形式に対応していることを確認してください。 #### サブスクリプションを移行する際の重要なフィールド お客様が自社で構築した実装システムで使用し、Stripe では使用していない関連サブスクリプションデータがある場合、Stripe で作成するサブスクリプションの `metadata` フィールドに、該当するデータを割り当てることができます。次の表で、サブスクリプションをインポートするときに重要な他のフィールドについて説明します。 | フィールド | 説明 | | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [customer](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-customer) | ソースデータの顧客 ID を Stripe の新しい顧客 ID に正しくマッピングしたことを確認します。 | | [phases.items.price](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-items-price) | ソースデータの価格 ID を Stripe の新しい価格 ID にマッピングしたことを確認します。 | | [current_phase.start_date](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-current_phase-start_date) | Stripe に定義するサブスクリプションスケジュールが、元のソースデータと一致し、連続性を保っていることを確認します。たとえば、ソースシステムで顧客の年次サブスクリプションが 6 カ月残っている場合、`billing_cycle_anchor` と `start_date` にサイクル途中の期間が正しく反映されていることを確認します。 | | サードパーティーメタデータ | ソースデータから追加のデータフィールドをインポートします。これには、商品名、プラン名、サードパーティーのアプリケーション ID などが含まれます。 | | Tax の設定 | 納税者番号、VAT ID、またはその他の税金情報を含めます。 | #### レガシー価格を準備する [レガシー料金](https://docs.stripe.com/billing/subscriptions/import-subscriptions.md#legacy-prices)のプレースホルダーを作成した場合、インポートするサブスクリプションと顧客にそれらの料金をマッピングする必要があります。レガシー料金があるサブスクリプションごとに、[Subscription (サブスクリプション)](https://docs.stripe.com/api/subscriptions.md#subscriptions) API の [price_data](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-items-price_data) パラメーターを使用して、料金とサブスクリプションに関する情報を渡します。必須フィールドは次のとおりです。 | パラメーター | 説明 | | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [currency](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-items-price_data-currency) | 3 文字の ISO 形式で示された価格の通貨。 | | [product](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-items-price_data-product) | プレースホルダー商品の ID。これは、すべてのレガシー価格に使用できます。 | | [recurring](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-items-price_data-recurring) | 継続価格の金額と頻度に関する情報。 | | [recurring.interval](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-items-price_data-recurring) | 間隔の頻度: `day`、`week`、`month`、`year` | | [recurring.interval_count](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-items-price_data-recurring-interval_count) | 請求の間隔の数。たとえば、`interval=day` と `interval_count=30` を設定すると、30 日ごとに顧客に請求するようになります。最大の間隔は 1 年 (1 年、12 カ月、または 52 週) です。 | | [recurring.unit_amount_decimal](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-items-price_data-unit_amount_decimal) | [unit_amount](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-items-price_data-unit_amount) と同様ですが、より細かい小数点以下の金額をセント単位で小数第 12 位まで指定することができます。`unit_amount` と `unit_amount_decimal` のいずれか一方のみを指定できます。 | ### Stripe にサブスクリプションデータをインポートする ソースデータの準備ができたら、Stripe へのサブスクリプションのインポートを開始できます。 #### テスト 本番環境でインポートを実行する前に、*サンドボックス* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes)を使用して、料金体系モデルのインポートプロセスを少なくとも 1 回実行します。スクリプトを再度マッピングする必要があります。 - サンドボックス内のデータを消去し、インポートを再実行した場合。 - サンドボックス環境と本番環境で価格 ID が異なることを理由に、本番環境へ移行する場合。 サンドボックスでは、[テストクロック](https://docs.stripe.com/billing/testing/test-clocks.md)を使用して、サブスクリプションの経過をシミュレートできます。これにより、移行対象のサブスクリプションが本番環境でどのように機能するかを確認できます。 #### サブスクリプションを作成する [Subscription (サブスクリプション)](https://docs.stripe.com/api/subscriptions.md) API を使用してもサブスクリプションを作成できますが、[Subscription Schedules (サブスクリプションスケジュール)](https://docs.stripe.com/api/subscription_schedules.md) API を使用することをお勧めします。この API を使用すると、将来に開始されるサブスクリプションをスケジュールできます。たとえば、月次サブスクリプションの開始までの日数が 30 日を超える場合は、これが唯一の方法になります。また、将来的にサブスクリプションを開始できるため、本番環境で顧客への請求を開始する前にインポート内容を確認できます。 さらに、Subscription Schedules API では `phases` も使用できます。これにより、細かい間隔での税金処理、回収方法、クーポンの使用などの設定をより柔軟に定義できます。間隔ごとに異なる処理を定義することも可能です。たとえば、年次サブスクリプションの最初の 3 カ月にのみクーポンを適用することができます。 2022年6月1日 0:00 UTC に開始するサブスクリプションを作成する方法を次に示します。 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "default_settings[billing_cycle_anchor]=phase_start" \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d start_date=1654066801 ``` ## 移行を確定する サブスクリプションをインポートしたら、API を使用してサブスクリプションが Stripe に存在することを確認します。 [List Subscription (サブスクリプションのリスト化)](https://docs.stripe.com/api/subscriptions/list.md) API を使用して、Stripe のすべての Subscription を表示します。[created](https://docs.stripe.com/api/subscriptions/list.md#list_subscriptions-created) パラメーターを渡して、最近作成された Subscription をフィルタリングできます。 ```curl curl -G https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "created[gt]=1647294709" ``` ## See also - [サブスクリプションスケジュール](https://docs.stripe.com/api/subscription_schedules.md)