Google Play Billing API v2 に offerPhase 追加！サブスク状態管理のベストプラクティスと API 併用のススメ

Google Play Billing API の v2（purchases.subscriptionsv2）に、待望の offerPhase 項目が追加されました。

これにより、ユーザーが現在「無料トライアル中」なのか「割引期間中」なのかを判定するのが非常に容易になりました。

しかし、実務レベルの実装においては、この API だけで完結させるには不十分な点もあります。

本記事では、新機能の解説と、「Subscriptions API v2」と「Orders API」をどう使い分けるべきかというベストプラクティスを考察します。

1. offerPhase の追加で何が変わったのか？

これまで、サブスクリプションの「現在のフェーズ（トライアル中か否か）」を正確に把握するには、過去の注文履歴を遡るか、orders API を個別に叩く必要がありました。
(または deprecated になっている、v1 の API の paymentState)

今回のアップデートにより、subscriptionsv2.get のレスポンスに含まれる lineItems 内で以下の状態が直接取得できるようになっています。

• FREE_TRIAL: 無料トライアル中
• INTRODUCTORY_PRICE: 割引価格での継続支払い中
• BASE_PRICE: 通常価格での支払い中
• PRORATION_PERIOD: 日割り計算期間

これにより、「今、ユーザーが特典を受けている状態かどうか」を 1 つの API で即座に判断できるようになったのが最大のメリットです。

2. 【注意点】Subscriptions API v2 だけでは足りない情報

offerPhase の追加は画期的ですが、実はこれだけでは「ユーザーに見せるべき詳細情報」を網羅できません。

限界：価格と正確な期間がわからない

subscriptionsv2 で取得できる currentPrice は、あくまでその商品のデフォルト価格や現在のフェーズの標準価格を示すに留まります。

• 具体的な割引額は？: 「50% OFF」なのか「月額 100 円」なのか、適用されている具体的なオファー内容は orders API の OfferPhaseDetails に軍配が上がります。
• フェーズの境界線は？: 無料トライアルが「いつ終わって」、次に「いくら請求されるか」の正確なタイムラインを組み立てるには、依然として注文単位の情報が必要です。

3. 実務でのベストプラクティス：API 併用戦略

結論として、高機能なサブスクリプション管理システムを構築する場合、以下の 「2 段階コール戦略」 が最も効率的です。

API の役割分担表

オファーの適用期間は expiryTime からもわかるのと、orders API でもトータルの期間ではなく現在のフェーズ単位の期間しかわからないので、厳密に orders API で確認しなくてもいいかもしれません。
(startTime も厳密に欲しい場合は orders API 一択ですね)

実装のフロー

1. RTDN（リアルタイム開発者通知）を受信: サブスクリプションの状態変化を検知。
2. Subscriptions v2 を実行: ユーザーの全体的な購読状態と offerPhase を確認。
3. 条件分岐:
   • offerPhase が BASE の場合：そのまま処理を完了。
   • offerPhase が FREE_TRIAL または INTRODUCTORY... の場合：さらに orders API を呼び出し、正確な割引価格や期間を取得して DB に保存。

4. API 割当数（クォータ）への影響は？

「API を 2 つ叩くと制限に引っかかるのでは？」という懸念があるかもしれませんが、基本的には心配無用です。

• 実行タイミングの限定: API を叩くのは「サブスクの状態が変わった時（RTDN 受信時）」や「ユーザーがアプリを起動した時（必要最小限）」のみです。
• 割当量の余裕: Google Play Developer API のデフォルトのクォータは非常に余裕を持って設定されており、1 ユーザーに対して数回のリクエストが増えたところで、通常の運用規模で制限に達することは稀です。

まとめ：よりスマートなサブスク実装へ

offerPhase の登場により、私たちのバックエンド実装は「状態判定」という点において非常にシンプルになりました。

しかし、ユーザーに対して「誠実な価格表示」や「マイページでの詳細な請求予定」を提供するためには、Subscriptions API v2 で「状態」を掴み、Orders API で「詳細（お金）」を補完するというハイブリッドなアプローチが、現時点での最適解と言えるでしょう。

新しい API を賢く使って、ユーザー体験の高いサブスクリプション機能を実装していきましょう！

saratoga

フリーランスエンジニア

XYouTube

仕事にも趣味にも IT を駆使するフリーランスエンジニア。技術的な TIPS や日々の生活の中で深堀りしてみたくなったことを備忘録として残していきます。