すべての App Store 購入に appAccountToken を付与せよ。さもなければ、その返金には反論できない

顧客が Apple に返金を申請し、Apple はあなたのサーバーに CONSUMPTION_REQUEST を送ります。あなたには、その人物が製品をどう使ったかについて実データで答えるための 12 時間があります。ところが通知を開いてみると、相手が誰なのかまったく分からないと気づきます。トランザクションには originalTransactionId と製品 id は載っていますが、あなた自身のデータベース内のアカウントを指し示すものは何もありません。その隙間こそ appAccountToken が埋めるものであり、購入時に設定しなかったのなら、その販売については後から埋めることはできません。

appAccountToken は、購入に付与する UUID です。生成された App Store のトランザクションが、あなたのシステム内の正確なユーザーを指すポインターを持つようにします。設定すれば、その顧客について Apple がこの先投げかけるすべての返金の問いに、相手の身元が添えられて届きます。省けば、あとは推測するしかありません。以下では、このフィールドが何であるか、どう設定するか、アプリ外の購入を救う新しいエンドポイント、そして返金が来たときにこの欠けたひも付けが実際にいくらの代償になるかを説明します。

appAccountToken とは実際に何か

appAccountToken は、あなたが生成し、購入の瞬間に StoreKit へ渡す不透明な UUID です。Apple はそれをトランザクションに保存し、その購入のトランザクション情報の中で返し、そこに残り続けます。Apple の言葉では、それは「トランザクションを、あなた自身のサービス上のユーザーのアカウントと関連付ける UUID」です。唯一の形式ルールは、それが UUID でなければならないということです。Apple はそれを読み取らず、何にマッピングされるかを検証せず、あなたの側でそれが何を意味するかを気にしません。それは、あなたが制御するひも付けです。

それはトランザクション上に存在するため、トランザクションが現れるあらゆる場所で戻ってきます。サーバー通知の署名付きトランザクション、App Store Server API の Get Transaction Info レスポンス、そしてサブスクリプションチェーン内のすべての更新は、最初の購入で設定していれば、いずれも同じトークンを持ちます。一つの UUID を一度付与すれば、その関係が続く限り、顧客の請求に付き従います。

本物の UUID でなければ、静かに消える

Apple が強制する唯一のルールは形式です。StoreKit 2 は RFC 4122 UUID を要求します。連結した文字列、整数の id、メールアドレスを渡しても、StoreKit はエラーを投げません。その値を破棄し、トランザクションは appAccountToken が nil に設定された状態で戻ってきます。開発者は絶えずこれに突き当たり、症状は常に同じで、Apple 自身のフォーラムで「appAccountToken is missing in the transaction payload」のような表現として現れ、ほぼ必ず、渡された値が有効な UUID でなかったことが原因です。サーバー側で本物の UUID を生成し、それをアカウントにひも付けて保存し、StoreKit には決してそれ以外のものを渡さないでください。

購入時にどう設定するか

StoreKit 2 では、単一の購入オプションです。ユーザーがサインアップするとき、または最初にチェックアウトに到達したときに、サーバーで UUID を生成し、そのアカウントのレコードに保存し、同じ値を購入呼び出しに渡します。

そのシグネチャは Product.PurchaseOption.appAccountToken(_ token: UUID) であり、購入は try await product.purchase(options: [.appAccountToken(token)]) のようになります。トランザクションが、App Store Server API を通じて検証されて、あるいはサーバー通知で届いて戻ってくると、それはその UUID を持っており、あなたのサーバーは一度のクエリで顧客を照会できます。

アカウントごとに一つの安定したトークンを使う

同じユーザーの購入ごとに新しいトークンを生成してはいけません。Apple は同じチェーン内の更新、請求リトライ、アップグレードでトークンを返すため、アカウントごとに安定した UUID があれば、最初の購入から将来のあらゆるイベントまで、きれいに一本の糸が通ります。購入ごとに変わるトークンはその糸を断ち切り、目的そのものを台無しにします。一つのアカウントに一つのトークン。そのアカウントが購入するたびに再利用します。

アプリ外の購入を救うエンドポイント

2025 年まで、一つの穴がありました。顧客がオファーコードを引き換えたり、App Store から直接プロモーションされたアプリ内購入を買ったりすると、あなたのアプリは購入フローを一度も実行しないため、appAccountToken を設定する場所がどこにもありませんでした。それらのトランザクションは匿名で届き、そのままの状態でした。

WWDC 2025 は、Set App Account Token エンドポイントでこの隙間をふさぎました。あなたのサーバーが App Store Server API で PUT /inApps/v1/transactions/{originalTransactionId}/appAccountToken を、本体に UUID を入れて呼び出すと、Apple はそのトランザクションにトークンを設定します。すべての製品タイプで機能し、オファーコードの引き換えとプロモーション購入を対象とし、送った値はトランザクション上にすでにあるトークンを上書きします。これで、アプリを一度も通さずに、サーバーから後づけで購入を関連付けられます。

欠けたひも付けが、どこであなたのお金を失わせるか

トークンの目的は、整った記録ではありません。Apple が開発者に投げかける唯一の返金の問い、すなわち CONSUMPTION_REQUEST は、それが関わる顧客を見つけられて初めて答えられる、ということです。

買い手が消耗型アイテムまたは非更新サブスクリプションについて返金を申請すると、Apple はあなたのサーバーに CONSUMPTION_REQUEST 通知を送り、Send Consumption Information で返信するための 12 時間を与えます。あなたの答えは、その特定の顧客に関するデータです。彼らが製品をどれだけ消費したか、アカウントの継続期間、生涯支出、提供状況。appAccountToken 自体がそのリクエスト内のフィールドの一つであり、さらに重要なのは、それこそが、通知のトランザクションを、あなたがこれから利用状況を説明しようとしているアカウントへとマッピングする手立てだということです。トークンがなければ、照会もなく、正確な答えもありません。

空白の答えが実際にいくらの代償になるか

識別できない返金は、悪い選択を強います。消費リクエストに何もなしで答えることもできますが、それは低消費と読み取られ、製品を大量に使った顧客も含めて、Apple を返金の承認へと傾かせます。あるいは推測することもできます。どちらにせよ、あなたは反論する証拠があった購入について返金しており、それらを提供する実際のコストはすでに支払っています。

そのコストは販売価格ではありません。一連のモデル API 呼び出しを実行し、画像を生成し、動画を書き出し、あるいはクリエイターへの支払いをトリガーした消耗型アイテムは、提供された瞬間に実際のお金を費やしました。返金は顧客の支払いを返します。しかしプロバイダーの請求書は返しません。識別できない一人の顧客に、その人が申請するすべての返金を掛け、さらに、あなたが相手を知らないことを当てにするすべての連続返金者を掛け合わせれば、あなたが省いたトークンは、あなたが決して書かなかった最も高価な一行のコードになります。

同じ考え方は Android にも、別の名前で存在する

Google Play は setObfuscatedAccountId で同一の問題を解決します。これは購入にアカウント識別子を付与し、orders.reviewrefund を通じた Google のチャージバック審査を、実在のユーザーに対して答えられるようにします。ストアが違い、仕組みが違っても、教訓は同じです。購入時に身元を付与するか、さもなければ後で争議に反論できないか、です。App Store では、そのツールが appAccountToken であり、UUID でなければなりません。

トークンを所定の場所に保つ三つの習慣

• アカウントごとに UUID を生成して保存する。顧客ごとに一つの安定したトークンを、サインアップ時または最初のチェックアウト時に作成し、そのレコードに保存して、すべての購入で再利用する。
• 渡す前に検証する。購入コードでその値が本物の UUID であることを確認し、不正な id が決してトランザクション上で静かに nil トークンにならないようにする。
• アプリ外の購入を補完する。トークンのないオファーコードの引き換えやプロモーション購入についてサーバー通知が届いたら、Set App Account Token エンドポイントを呼び出して正しいものを付与する。

この三つを行えば、Apple がこの先あなたに送るすべてのトランザクションは、返金リクエストも含めて、それが属する顧客にすでにひも付いた状態で届きます。

これが RefundHalt が依存する土台です。私たちはすべてのトランザクションとサーバー通知から appAccountToken を読み取り、そのアカウントについて私たちがすでに追跡している利用状況とひも付け、12 時間の枠内で顧客の実際の数字を使って Apple の消費リクエストに答えます。トークンはその糸です。一度設定すれば、あなたの返金防御はつかまるものを手にします。