Developer / Subscriptions API

SubscriptionContractCalculation API
サブスク契約の編集を「チェックアウトと同じエンジン」で計算

契約の編集内容が Shopify のチェックアウトエンジンで計算されるようになった。Shopify Functions が効き、請求時に購読者が見る内容と揃い、保存前に合計・配送オプション・警告をプレビューできる。SubscriptionDraft API からの移行が推奨。

このページの構成
  1. そもそも何が変わるのか(30秒で理解)
  2. 仕組み図解 : 契約編集が計算されるまでの流れ
  3. 新しくできるようになる3つのこと
  4. SubscriptionDraft API vs SubscriptionContractCalculation API
  5. 対象者と移行の位置づけ
  6. 移行の進め方(3ステップ)
  7. 技術者が押さえるべき5つのポイント
  8. 業務に活かせる3つのユースケース
  9. 提案で使える1行サマリ

1そもそも何が変わるのか

サブスクリプション契約を管理する新しい API SubscriptionContractCalculation API が使えるようになった。
契約の編集内容が Shopify のチェックアウトエンジン を通って計算されるため、通常のチェックアウトと同じ計算ロジックが契約編集にも適用される。

従来 : SubscriptionDraft API

引き続き使える。ただし今回発表された新機能(Functions 対応・請求時との一致・計算済みプレビュー)には対応しない。

新規 : SubscriptionContractCalculation API

契約編集をチェックアウトエンジンで計算。Shopify Functions が効き、保存前に計算結果をまるごとプレビューできる。

2仕組み図解 : 契約編集が計算されるまでの流れ

契約の編集 アプリ/開発者が 変更内容を渡す STEP 1 Shopify チェックアウトエンジン Shopify Functions:cart transform Shopify Functions:delivery customization 請求時と同じ計算 STEP 2 : 計算 計算済み契約のプレビュー 合計(totals) 配送オプション 警告(warnings) STEP 3 : 保存前に確認 変更を保存 STEP 4
ポイントは 「保存(persist)する前に」 計算結果を確認できること。変更を確定する前に、合計金額・配送オプション・警告を含む契約全体の計算結果を取得できる。
具体的なミューテーション名・フィールド名は本記事に記載なし。移行ガイドと API ドキュメントを参照。

3新しくできるようになる3つのこと

fx Functions

Shopify Functions が効く

cart transform(カート変換)や delivery customization(配送カスタマイズ)などの Shopify Functions が、契約の計算時にもサポートされる。

= 一致

請求時の内容と揃う

契約の編集結果が、購読者が請求時に目にする内容と一致する。編集時と請求時で計算がズレない。

プレビュー

保存前にフルプレビュー

合計・配送オプション・警告を含む「計算済み契約の全体像」を、変更を保存する前に取得できる。

4SubscriptionDraft API vs SubscriptionContractCalculation API

項目SubscriptionDraft API(従来)SubscriptionContractCalculation API(新)
提供状況 継続提供 引き続き利用可能 提供開始 利用可能
計算エンジン 記載なし チェックアウトエンジン を通して計算
Shopify Functions 新機能は非対応 対応 cart transform/delivery customization など
請求時との一致 新機能は非対応 対応 購読者が請求時に見る内容と揃う
保存前プレビュー 新機能は非対応 対応 合計・配送オプション・警告
廃止予定日 記載なし —

5対象者と移行の位置づけ

SubscriptionDraft API を使っている開発者

SubscriptionContractCalculation API へ移行すべき(should migrate)と明記されている。

用意されている資料

移行ガイド、更新されたサブスクリプションのビルドガイド、API ドキュメントが案内されている。

対象 API バージョン、必要なアクセススコープ、対象プラン、SubscriptionDraft API の廃止時期は本記事に記載なし。移行ガイドと API ドキュメントで確認すること。

6移行の進め方(3ステップ)

1

移行ガイドを読む

公式の migration guide と更新された build guides/API docs を確認。

2

Draft 利用箇所を置き換え

SubscriptionDraft API で契約編集している処理を新 API に切り替える。

3

プレビューで検証

保存前に合計・配送オプション・警告を確認し、意図どおりの計算か検証する。

SubscriptionDraft API は引き続き使えるので、既存実装がすぐ壊れるわけではない。ただし新機能を使うには移行が必要。

7技術者が押さえるべき5つのポイント

1. 計算ロジックがチェックアウトと共通化

契約編集がチェックアウトエンジンを通るため、通常購入と同じ計算系に乗る。サブスク専用の計算を自前で再現する必要が減る。

fx

2. 既存の Functions が契約編集にも効く

cart transform・delivery customization などがサポート対象として明記。「など(including)」とあるため、その他の Function 種別の対応範囲は API ドキュメントで確認が必要。

3. 「計算」と「保存」が分離されている

保存前に計算済み契約(totals・delivery options・warnings)を取得できる。警告をハンドリングしてから確定する UI/処理設計が可能。

=

4. 編集時と請求時のズレを解消

編集内容が購読者の請求時の表示と揃う。編集画面で見せた金額と実請求の不一致による問い合わせリスクを下げられる。

5. SubscriptionDraft API は「残るが伸びない」

Draft API は利用可能なまま、新機能はサポートしない。新規実装は最初から SubscriptionContractCalculation API で組み、既存実装は移行計画を立てるのが妥当。廃止時期は記載なし。

8業務に活かせる3つのユースケース

SET
USE CASE 1

バンドル/セット商品の定期便で、契約変更時も同じ構成ロジックを適用

課題
通常購入では cart transform でセット商品を組んでいるが、定期契約の編集時に同じロジックが効かず、内容や金額の扱いが通常購入と食い違う。
打ち手
契約編集を SubscriptionContractCalculation API に移行し、既存の cart transform を契約計算にも効かせる。
効果
通常購入と定期便で商品構成ロジックを一本化でき、二重実装や運用ルールの差分を減らせる。
技術メモ
cart transform は契約計算時のサポート対象として明記。実際の挙動は移行ガイドとテスト環境で確認する。
配送オプション
USE CASE 2

会員マイページでの配送変更を「確定前プレビュー」付きにする

課題
購読者が配送先や配送方法を変えたとき、変更後の合計や選べる配送オプションが確定前に分からず、変更後の請求で驚かせてしまう。
打ち手
変更内容を新 API で計算し、合計・配送オプション・警告を画面に出してから購読者に確定してもらう。
効果
請求時の内容と揃った金額を事前提示でき、「思っていた金額と違う」問い合わせや解約リスクを下げられる。
技術メモ
delivery customization も契約計算時のサポート対象。警告(warnings)を UI でどう見せるかを設計に含める。
USE CASE 3

サポート担当による契約修正の事故防止

課題
CS 担当が問い合わせ対応で契約内容を修正する際、保存してから金額の誤りに気づき、再修正や返金対応が発生している。
打ち手
社内向け契約編集ツールを新 API ベースにし、保存前に計算済み契約(合計・配送・警告)を必ず確認するフローにする。
効果
保存前チェックで修正ミスを減らし、再対応や返金の手戻りを削減できる。
技術メモ
既存ツールが SubscriptionDraft API ベースならそのまま動くが、プレビュー機能を使うには移行が必要。

9提案で使える1行サマリ

「サブスク契約の編集を、Shopify のチェックアウトエンジンで計算する新 API。
Functions が効き、請求時と同じ結果を、保存前にプレビューできる。
SubscriptionDraft API 利用中なら、新機能を使うために移行を計画すべき。」