POST /api/v2/server-side-api/vc/transactions/

仮想通貨トランザクションを作成する

1回のアトミックなトランザクションで、プロファイルに対して1つ以上の仮想通貨をクレジットまたはデビットします。クレジット(付与)には正の amount を、デビット(消費)には負の amount を使用してください。すべてのアイテムは一括で適用されます。いずれかのアイテムが失敗した場合、何も適用されません。

1リクエストにつき、各通貨コードは1回のみ指定できます。このエンドポイントを通じたクレジットは、常に有効期限なしの残高として作成されます。

仮想通貨アナリティクスでトランザクションを活用するには、operation と feature でラベルを付けてください。すべてのラベルフィールドは任意です。items と metadata のみのリクエストは operation: null として保存されます。

Header parameters

adapty-customer-user-idstring

お客様のシステムにおける顧客の一意のID。adapty-customer-user-id または adapty-profile-id のいずれかが必須です。

adapty-profile-idstring

お客様のシステムにおけるプロファイルの一意のID。匿名プロファイルを扱う場合に最適な選択肢です。adapty-customer-user-id または adapty-profile-id のいずれかが必須です。

Idempotency-Keystring · uuid

リクエストをべき等にするUUID v4。同じキーでリクエストを再試行した場合、Adaptyは残高を再度変更せず、元のトランザクションの結果を返します。有効なUUID v4である必要があります。

キーは最大1時間、単一のプロファイルのスコープで記憶されます。その時間が経過すると、同じキーでのリクエストは新しいトランザクションとして適用されます。そのため、このキーは長期的な付与の重複排除ではなく、コールの安全な再試行のためにのみ使用してください。

Request body

仮想通貨トランザクションを作成するためのリクエストボディ。

itemsarray of objectrequired

アトミックに適用する残高調整。各通貨コードは1回のみ使用可能です。

currency_codestringrequired

調整するバーチャル通貨コード。

amountintegerrequired

適用する金額。正の値は通貨を付与(クレジット)し、負の値は通貨を消費(デビット)します。ゼロは指定できません。

metadataobject

トランザクションとともに保存されるオプションのキーと値のペア。キーは最大5件。各キーは ^[a-z0-9_]{1,30}$ に一致し、各値は最大200文字です。

operationstring

トランザクションの意味を示します。ほとんどのインテグレーションで必要な値は 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"

featurestring

コインが使用された、または付与された対象。1単語で、オプションとしてドットで区切られたサブタイプを1つ持てます: ^[a-zA-Z0-9_]{1,32}(\.[a-zA-Z0-9_]{1,32})?$ に一致する必要があります。送信された形式のまま、大文字・小文字を区別して保存されます。価格、ティア、バージョン、バリアントはエンコードしないでください。例: power_up.extra_life。

customer_placement_idstring

操作が発生したアプリ内の画面またはプレースメントのID。これはAdaptyのプレースメントIDではなく、あなた自身のIDです。^[a-zA-Z0-9_.-]{1,128}$ に一致する必要があります。送信された形式のまま保存されます。例: onboarding-step-3。

reference_idstring

生成、報酬、サポートチケットなど、あなたのシステム内の関連オブジェクトのID。1〜128文字。制御文字、BIDI文字、ゼロ幅文字は拒否されます。個人情報を含めないでください。例: ticket_48213。

is_sandboxboolean

テスト中に付与するコインの場合は true に設定してください。

storestring

このトランザクションが参照する購入のストア: app_store、play_store、stripe、paddle、またはアプリに設定されたカスタムストアのID。最大30文字。ストアで購入が返金された場合、この参照でクレジットされたコインは取り戻されます。store_transaction_id と合わせて送信してください。

store_transaction_idstring

その購入のストアトランザクションID。最大50文字。これは参照にすぎません: Adaptyはその存在や一意性を確認しません。store と合わせて送信してください。

Responses

トランザクションが作成されました。ボディは作成されたトランザクションで、トランザクション履歴の1アイテムと同じ形式に加え、トランザクション後の残高が含まれます。

Schema

作成されたトランザクション。トランザクション履歴のアイテムと同じ形式に、トランザクション後の残高を加えたものです。

transaction_idstring

トランザクションの一意なID。

transaction_typestring

トランザクションのソース。store_purchase、subscription_renewal、trial_start、api_transaction、dashboard_transaction、refund、またはexpiryのいずれか。

itemsarray of object

このトランザクションに記録された通貨ごとの残高変更。

currency_codestringrequired

バーチャル通貨コード。

amountintegerrequired

残高に適用された符号付き変化量。正の値はクレジット、負の値はデビットを表します。

balance_afterintegerrequired

このトランザクション適用後の通貨残高。

metadataobject

トランザクションに保存されたキーと値のペア(存在する場合)。

operationstring

トランザクションの意味。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"

featurestring

コインが消費された目的または付与された理由(送信した値)。Adaptyが作成したトランザクションではnull。

customer_placement_idstring

アプリ側のスクリーンまたはプレースメントID(送信した値)。Adaptyが作成したトランザクションではnull。

reference_idstring

自社システム内の関連オブジェクトのID(送信した値)。Adaptyが作成したトランザクションではnull。

is_sandboxboolean

テスト用トランザクションかどうか。Adaptyが作成したトランザクションの場合、ストア購入の環境に従います。api_transactionの場合は送信した値が使用され、デフォルトはfalseです。

storestring

関連する購入のストア。ストアイベント(購入、更新、トライアル、返金)からAdaptyが作成したトランザクション、および購入参照とともに送信されたapi_transactionに設定されます。

store_transaction_idstring

関連する購入のストアトランザクションID。storeと同じトランザクションに設定されます。

created_atstring

トランザクションが記録された日時。

response_created_atinteger

レスポンスが生成された日時(Unixタイムスタンプ、ミリ秒単位)。

balancesarray of object

このリクエストによって影響を受けた各通貨のトランザクション後の残高(items の各アイテムに対して1エントリ)。プロファイルの残高リスト全体を取得するには、GET /api/v2/server-side-api/vc/balances/ を使用してください。

codestringrequired

仮想通貨コード。

namestringrequired

仮想通貨の表示名。

balanceintegerrequired

現在保留中の金額を含む合計残高。

heldintegerrequired

すべてのアクティブな保留(予約済み金額)の合計。現在は常に 0。

availableintegerrequired

使用可能な残高。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
errorsarray of objectrequired
sourcestring

エラーの発生源

errorsarray of string

エラーメッセージの配列

error_codestringrequired

エラーの短い名称

status_codeintegerrequired

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
errorsarray of objectrequired
sourcestring

エラーの発生源

errorsarray of string

エラーメッセージの配列

error_codestringrequired

エラーの短い名称

status_codeintegerrequired

HTTPステータスコード

プロファイルが見つかりません(error_code は profile_does_not_exist)。

Schema
errorsarray of objectrequired
sourcestring

エラーの発生源

errorsarray of string

エラーメッセージの配列

error_codestringrequired

エラーの短い名称

status_codeintegerrequired

HTTPステータスコード

競合。同じ Idempotency-Key を持つリクエストがまだ処理中です(error_code は idempotency_in_flight)。Retry-After レスポンスヘッダーの間隔後に再試行してください。

Schema
errorsarray of objectrequired
sourcestring

エラーの発生源

errorsarray of string

エラーメッセージの配列

error_codestringrequired

エラーの短い名称

status_codeintegerrequired

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
errorsarray of objectrequired
sourcestring

エラーの発生源

errorsarray of string

エラーメッセージの配列

error_codestringrequired

エラーの短い名称

status_codeintegerrequired

HTTPステータスコード

内部サーバーエラー