/api/v2/server-side-api/vc/transactions/ 仮想通貨トランザクションを作成する
1回のアトミックなトランザクションで、プロファイルに対して1つ以上の仮想通貨をクレジットまたはデビットします。クレジット(付与)には正の amount を、デビット(消費)には負の amount を使用してください。すべてのアイテムは一括で適用されます。いずれかのアイテムが失敗した場合、何も適用されません。
1リクエストにつき、各通貨コードは1回のみ指定できます。このエンドポイントを通じたクレジットは、常に有効期限なしの残高として作成されます。
仮想通貨アナリティクスでトランザクションを活用するには、operation と feature でラベルを付けてください。すべてのラベルフィールドは任意です。items と metadata のみのリクエストは operation: null として保存されます。
Header parameters
お客様のシステムにおける顧客の一意のID。adapty-customer-user-id または adapty-profile-id のいずれかが必須です。
お客様のシステムにおけるプロファイルの一意のID。匿名プロファイルを扱う場合に最適な選択肢です。adapty-customer-user-id または adapty-profile-id のいずれかが必須です。
リクエストをべき等にするUUID v4。同じキーでリクエストを再試行した場合、Adaptyは残高を再度変更せず、元のトランザクションの結果を返します。有効なUUID v4である必要があります。
キーは最大1時間、単一のプロファイルのスコープで記憶されます。その時間が経過すると、同じキーでのリクエストは新しいトランザクションとして適用されます。そのため、このキーは長期的な付与の重複排除ではなく、コールの安全な再試行のためにのみ使用してください。
Request body
仮想通貨トランザクションを作成するためのリクエストボディ。
アトミックに適用する残高調整。各通貨コードは1回のみ使用可能です。
調整するバーチャル通貨コード。
適用する金額。正の値は通貨を付与(クレジット)し、負の値は通貨を消費(デビット)します。ゼロは指定できません。
トランザクションとともに保存されるオプションのキーと値のペア。キーは最大5件。各キーは ^[a-z0-9_]{1,30}$ に一致し、各値は最大200文字です。
トランザクションの意味を示します。ほとんどのインテグレーションで必要な値は spend、spend_reversal、reward、reward_reversal の4つです。省略した場合、トランザクションは保存され operation: null として返されます。
値: top_up — 購入、サブスクリプション、またはトライアルによってクレジットされたコイン; refund — 返金により取り戻されたコイン; spend — 機能またはコンテンツに使用したコイン; spend_reversal — 生成失敗などの失敗したアクションのために返却されたコイン; reward — ボーナス、報酬、またはサポート補償; reward_reversal — 取り戻された報酬; exchange — 1つのトランザクション内での通貨間の変換(符号が逆のアイテムを含む); expiry — 期限切れになったコイン; migration — 独自システムから移動された残高; adjustment — アプリ内経済の外部における技術的な残高修正。
One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"
コインが使用された、または付与された対象。1単語で、オプションとしてドットで区切られたサブタイプを1つ持てます: ^[a-zA-Z0-9_]{1,32}(\.[a-zA-Z0-9_]{1,32})?$ に一致する必要があります。送信された形式のまま、大文字・小文字を区別して保存されます。価格、ティア、バージョン、バリアントはエンコードしないでください。例: power_up.extra_life。
操作が発生したアプリ内の画面またはプレースメントのID。これはAdaptyのプレースメントIDではなく、あなた自身のIDです。^[a-zA-Z0-9_.-]{1,128}$ に一致する必要があります。送信された形式のまま保存されます。例: onboarding-step-3。
生成、報酬、サポートチケットなど、あなたのシステム内の関連オブジェクトのID。1〜128文字。制御文字、BIDI文字、ゼロ幅文字は拒否されます。個人情報を含めないでください。例: ticket_48213。
テスト中に付与するコインの場合は true に設定してください。
このトランザクションが参照する購入のストア: app_store、play_store、stripe、paddle、またはアプリに設定されたカスタムストアのID。最大30文字。ストアで購入が返金された場合、この参照でクレジットされたコインは取り戻されます。store_transaction_id と合わせて送信してください。
その購入のストアトランザクションID。最大50文字。これは参照にすぎません: Adaptyはその存在や一意性を確認しません。store と合わせて送信してください。
Responses
トランザクションが作成されました。ボディは作成されたトランザクションで、トランザクション履歴の1アイテムと同じ形式に加え、トランザクション後の残高が含まれます。
Schema
作成されたトランザクション。トランザクション履歴のアイテムと同じ形式に、トランザクション後の残高を加えたものです。
トランザクションの一意なID。
トランザクションのソース。store_purchase、subscription_renewal、trial_start、api_transaction、dashboard_transaction、refund、またはexpiryのいずれか。
このトランザクションに記録された通貨ごとの残高変更。
バーチャル通貨コード。
残高に適用された符号付き変化量。正の値はクレジット、負の値はデビットを表します。
このトランザクション適用後の通貨残高。
トランザクションに保存されたキーと値のペア(存在する場合)。
トランザクションの意味。Adaptyは自身が作成するトランザクションに対して自動的に設定します。store_purchase、subscription_renewal、trial_startにはtop_upが、refundにはrefundが、expiryにはexpiryが設定されます。dashboard_transactionの場合は、チームメンバーがAdapty ダッシュボードで残高を調整した際に選択した操作が設定されます。api_transactionの場合は、送信した値、または送信しなかった場合はnullが設定されます。
One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"
コインが消費された目的または付与された理由(送信した値)。Adaptyが作成したトランザクションではnull。
アプリ側のスクリーンまたはプレースメントID(送信した値)。Adaptyが作成したトランザクションではnull。
自社システム内の関連オブジェクトのID(送信した値)。Adaptyが作成したトランザクションではnull。
テスト用トランザクションかどうか。Adaptyが作成したトランザクションの場合、ストア購入の環境に従います。api_transactionの場合は送信した値が使用され、デフォルトはfalseです。
関連する購入のストア。ストアイベント(購入、更新、トライアル、返金)からAdaptyが作成したトランザクション、および購入参照とともに送信されたapi_transactionに設定されます。
関連する購入のストアトランザクションID。storeと同じトランザクションに設定されます。
トランザクションが記録された日時。
レスポンスが生成された日時(Unixタイムスタンプ、ミリ秒単位)。
このリクエストによって影響を受けた各通貨のトランザクション後の残高(items の各アイテムに対して1エントリ)。プロファイルの残高リスト全体を取得するには、GET /api/v2/server-side-api/vc/balances/ を使用してください。
仮想通貨コード。
仮想通貨の表示名。
現在保留中の金額を含む合計残高。
すべてのアクティブな保留(予約済み金額)の合計。現在は常に 0。
使用可能な残高。balance - held として計算されます。
Example
{
"transaction_id": "019a7c3e-5b2a-7c1d-9e4f-0a1b2c3d4e5f",
"transaction_type": "api_transaction",
"items": [
{
"currency_code": "COINS",
"amount": -10,
"balance_after": 90
}
],
"metadata": null,
"operation": "spend",
"feature": "power_up.extra_life",
"customer_placement_id": "level-complete",
"reference_id": "session_7781",
"is_sandbox": false,
"store": null,
"store_transaction_id": null,
"created_at": "2026-11-12T10:00:00.123Z",
"response_created_at": 1794477600123,
"balances": [
{
"code": "COINS",
"name": "Coins",
"balance": 90,
"held": 0,
"available": 90
}
]
} 不正なリクエスト。error_code フィールドで原因を特定できます:
validation_error— ボディまたはヘッダーが無効です。例えば、ラベルフィールドのフォーマットが不正、itemsが空または20件を超えている、amountが0またはint32の範囲外、通貨コードが重複している、metadataの制約違反、adapty-profile-idおよびadapty-customer-user-idのいずれも送信されていないなどが該当します。errors[].sourceにフィールド名が示されます。storeをstore_transaction_idなしで送信した場合など、複数フィールドにまたがるチェックではsourceは空文字列になります。parse_error— ボディが有効なJSONではありません。idempotency_key_invalid—Idempotency-KeyがUUID v4ではありません。unknown_currency— 通貨がアプリに設定されていません。unknown_store—storeがアプリに設定されていないカスタムストアです。insufficient_balance— デビット額が利用可能残高を超えています。balance_overflow— クレジットにより残高がint32の範囲を超えます。
Schema
エラーの発生源
エラーメッセージの配列
エラーの短い名称
HTTPステータスコード
Example
{
"errors": [
{
"source": "feature",
"errors": [
"String should match pattern '^[a-zA-Z0-9_]{1,32}(\\.[a-zA-Z0-9_]{1,32})?$'"
]
}
],
"error_code": "validation_error",
"status_code": 400
} 認証エラー。APIキーが欠落しているか無効です(error_code は not_authenticated)。
Schema
エラーの発生源
エラーメッセージの配列
エラーの短い名称
HTTPステータスコード
プロファイルが見つかりません(error_code は profile_does_not_exist)。
Schema
エラーの発生源
エラーメッセージの配列
エラーの短い名称
HTTPステータスコード
競合。同じ Idempotency-Key を持つリクエストがまだ処理中です(error_code は idempotency_in_flight)。Retry-After レスポンスヘッダーの間隔後に再試行してください。
Schema
エラーの発生源
エラーメッセージの配列
エラーの短い名称
HTTPステータスコード
Example
{
"errors": [
{
"source": null,
"errors": [
"A similar request is being processed."
]
}
],
"error_code": "idempotency_in_flight",
"status_code": 409
} リクエストが多すぎます。アプリごとまたはグローバルのレート制限を超えました(error_code は rate_limited)。デフォルトの制限は、アプリごとに毎分600リクエスト、グローバルで毎分6000リクエストです。
Schema
エラーの発生源
エラーメッセージの配列
エラーの短い名称
HTTPステータスコード
内部サーバーエラー