/api/v2/server-side-api/vc/transactions/ Create virtual currency transaction
Credits or debits one or more virtual currencies for a profile in a single atomic transaction. Use a positive amount to credit (grant) and a negative amount to debit (spend). All items are applied together — if any item fails, none are applied.
Each currency code may appear only once per request. A credit through this endpoint always creates a non-expiring balance.
To make the transaction usable in virtual currency analytics, label it with operation and feature. All labeling fields are optional: a request with only items and metadata is saved with operation: null.
Header parameters
The unique ID of the customer in your system. Either adapty-customer-user-id or adapty-profile-id is required.
The unique ID of the profile in your system. Your best option if you are working with anonymous profiles. Either adapty-customer-user-id or adapty-profile-id is required.
A UUID v4 that makes the request idempotent. If you retry a request with the same key, Adapty returns the result of the original transaction without changing balances again. Must be a valid UUID v4.
Keys are remembered for up to an hour, scoped to a single profile. After that window, a request with the same key is applied as a new transaction — so use the key to retry a call safely, not to deduplicate a grant over the long term.
Request body
Request body for creating a virtual currency transaction.
Balance adjustments to apply atomically. Each currency code may appear only once.
The virtual currency code to adjust.
The amount to apply. A positive value credits (grants) the currency; a negative value debits (spends) it. Cannot be zero.
Optional key-value pairs stored with the transaction. At most 5 keys. Each key matches ^[a-z0-9_]{1,30}$, and each value is at most 200 characters.
What the transaction means. Most integrations need four values: spend, spend_reversal, reward, reward_reversal. If omitted, the transaction is saved and returned with operation: null.
Values: top_up — coins credited for a purchase, a subscription, or a trial; refund — coins taken back because the money was refunded; spend — coins spent on a feature or content; spend_reversal — coins returned for a failed action, such as a failed generation; reward — a bonus, a reward, or a support compensation; reward_reversal — a reward taken back; exchange — a conversion between currencies in one transaction, with items of opposite signs; expiry — coins expired; migration — balances moved from your own system; adjustment — a technical balance correction outside the in-app economy.
One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"
What the coins were spent on or granted for. One word, optionally with one dotted subtype: must match ^[a-zA-Z0-9_]{1,32}(\.[a-zA-Z0-9_]{1,32})?$. Stored as sent, case-sensitive. Do not encode price, tier, version, or variant. Example: power_up.extra_life.
ID of the screen or placement in your app where the operation happened. This is your own ID, not an Adapty placement ID. Must match ^[a-zA-Z0-9_.-]{1,128}$. Stored as sent. Example: onboarding-step-3.
ID of the related object in your system, such as a generation, a reward, or a support ticket. 1–128 characters; control, BIDI, and zero-width characters are rejected. Do not put personal data here. Example: ticket_48213.
Set to true for coins you grant while testing.
Store of the purchase this transaction refers to: app_store, play_store, stripe, paddle, or the ID of a custom store set up in the app. Up to 30 characters. If the purchase is refunded in the store, the coins credited with this reference are clawed back. Send together with store_transaction_id.
Store transaction ID of that purchase. Up to 50 characters. It is only a reference: Adapty does not check that it exists or is unique. Send together with store.
Responses
Transaction created. The body is the created transaction, in the same shape as an item of the transaction history, plus the post-transaction balances.
Schema
The created transaction, in the same shape as an item of the transaction history, plus the post-transaction balances.
Unique ID of the transaction.
The source of the transaction. One of store_purchase, subscription_renewal, trial_start, api_transaction, dashboard_transaction, refund, or expiry.
Per-currency balance changes recorded in this transaction.
The virtual currency code.
The signed change applied to the balance. A positive value is a credit, a negative value is a debit.
The currency balance after this transaction was applied.
Key-value pairs stored with the transaction, if any.
What the transaction means. Adapty sets it on its own transactions: store_purchase, subscription_renewal, and trial_start get top_up, refund gets refund, and expiry gets expiry. On a dashboard_transaction, it is the operation a team member selected when they adjusted the balance in the Adapty Dashboard. On an api_transaction, it is the value you sent, or null if you sent none.
One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"
What the coins were spent on or granted for, as you sent it. null on transactions created by Adapty.
The screen or placement ID from your app, as you sent it. null on transactions created by Adapty.
The ID of the related object in your system, as you sent it. null on transactions created by Adapty.
Whether the transaction is a test one. On transactions created by Adapty, it follows the environment of the store purchase. On an api_transaction, it is the value you sent, false by default.
Store of the related purchase. Set on transactions created by Adapty from store events (purchase, renewal, trial, refund), and on an api_transaction sent with a purchase reference.
Store transaction ID of the related purchase. Set on the same transactions as store.
When the transaction was recorded.
When the response was generated, as a Unix timestamp in milliseconds.
Post-transaction balance for each currency affected by this request (one entry per item in items). To read the full balance list for the profile, use GET /api/v2/server-side-api/vc/balances/.
Virtual currency code.
Display name of the virtual currency.
Total balance, including amounts currently held.
Sum of all active holds (reserved amounts). Currently always 0.
Balance available to spend, computed as 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
}
]
} Bad request. The error_code field identifies the cause:
validation_error— the body or headers are invalid. For example, a labeling field breaks its format,itemsis empty or has more than 20 entries, anamountis 0 or out of the int32 range, a currency code repeats,metadatabreaks its constraints, or neitheradapty-profile-idnoradapty-customer-user-idis sent.errors[].sourcenames the field. For a check that spans several fields, such asstoresent withoutstore_transaction_id,sourceis an empty string.parse_error— the body is not valid JSON.idempotency_key_invalid—Idempotency-Keyis not a UUID v4.unknown_currency— the currency is not set up in the app.unknown_store—storeis a custom store that is not set up in the app.insufficient_balance— a debit exceeds the available balance.balance_overflow— a credit would take the balance beyond the int32 range.
Schema
Source of the error
Array of error messages
Short error name
HTTP status code
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
} Unauthorized. The API key is missing or invalid (error_code is not_authenticated).
Schema
Source of the error
Array of error messages
Short error name
HTTP status code
Profile not found (error_code is profile_does_not_exist).
Schema
Source of the error
Array of error messages
Short error name
HTTP status code
Conflict. A request with the same Idempotency-Key is still being processed (error_code is idempotency_in_flight). Retry after the interval in the Retry-After response header.
Schema
Source of the error
Array of error messages
Short error name
HTTP status code
Example
{
"errors": [
{
"source": null,
"errors": [
"A similar request is being processed."
]
}
],
"error_code": "idempotency_in_flight",
"status_code": 409
} Too many requests. The per-app or global rate limit was exceeded (error_code is rate_limited). The default limits are 600 requests per minute per app and 6000 requests per minute globally.
Schema
Source of the error
Array of error messages
Short error name
HTTP status code
Internal server error