POST /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

adapty-customer-user-idstring

The unique ID of the customer in your system. Either adapty-customer-user-id or adapty-profile-id is required.

adapty-profile-idstring

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.

Idempotency-Keystring · uuid

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.

itemsarray of objectrequired

Balance adjustments to apply atomically. Each currency code may appear only once.

currency_codestringrequired

The virtual currency code to adjust.

amountintegerrequired

The amount to apply. A positive value credits (grants) the currency; a negative value debits (spends) it. Cannot be zero.

metadataobject

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.

operationstring

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"

featurestring

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.

customer_placement_idstring

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.

reference_idstring

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.

is_sandboxboolean

Set to true for coins you grant while testing.

storestring

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_idstring

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.

transaction_idstring

Unique ID of the transaction.

transaction_typestring

The source of the transaction. One of store_purchase, subscription_renewal, trial_start, api_transaction, dashboard_transaction, refund, or expiry.

itemsarray of object

Per-currency balance changes recorded in this transaction.

currency_codestringrequired

The virtual currency code.

amountintegerrequired

The signed change applied to the balance. A positive value is a credit, a negative value is a debit.

balance_afterintegerrequired

The currency balance after this transaction was applied.

metadataobject

Key-value pairs stored with the transaction, if any.

operationstring

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"

featurestring

What the coins were spent on or granted for, as you sent it. null on transactions created by Adapty.

customer_placement_idstring

The screen or placement ID from your app, as you sent it. null on transactions created by Adapty.

reference_idstring

The ID of the related object in your system, as you sent it. null on transactions created by Adapty.

is_sandboxboolean

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.

storestring

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_idstring

Store transaction ID of the related purchase. Set on the same transactions as store.

created_atstring

When the transaction was recorded.

response_created_atinteger

When the response was generated, as a Unix timestamp in milliseconds.

balancesarray of object

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/.

codestringrequired

Virtual currency code.

namestringrequired

Display name of the virtual currency.

balanceintegerrequired

Total balance, including amounts currently held.

heldintegerrequired

Sum of all active holds (reserved amounts). Currently always 0.

availableintegerrequired

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, items is empty or has more than 20 entries, an amount is 0 or out of the int32 range, a currency code repeats, metadata breaks its constraints, or neither adapty-profile-id nor adapty-customer-user-id is sent. errors[].source names the field. For a check that spans several fields, such as store sent without store_transaction_id, source is an empty string.
  • parse_error — the body is not valid JSON.
  • idempotency_key_invalid — Idempotency-Key is not a UUID v4.
  • unknown_currency — the currency is not set up in the app.
  • unknown_store — store is 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
errorsarray of objectrequired
sourcestring

Source of the error

errorsarray of string

Array of error messages

error_codestringrequired

Short error name

status_codeintegerrequired

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

Source of the error

errorsarray of string

Array of error messages

error_codestringrequired

Short error name

status_codeintegerrequired

HTTP status code

Profile not found (error_code is profile_does_not_exist).

Schema
errorsarray of objectrequired
sourcestring

Source of the error

errorsarray of string

Array of error messages

error_codestringrequired

Short error name

status_codeintegerrequired

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

Source of the error

errorsarray of string

Array of error messages

error_codestringrequired

Short error name

status_codeintegerrequired

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

Source of the error

errorsarray of string

Array of error messages

error_codestringrequired

Short error name

status_codeintegerrequired

HTTP status code

Internal server error