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

List virtual currency transactions

Returns the virtual currency transaction history for a profile, newest first. Results use cursor pagination: when the response includes a non-null pagination.next_cursor, pass it back as the cursor query parameter to fetch the next page.

Query parameters

currency_codestring

Filter the history to a single virtual currency code.

cursorstring

Opaque pagination cursor returned as pagination.next_cursor in a previous response. Omit to fetch the first page.

limitinteger

Maximum number of transactions to return per page. Defaults to 50.

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.

Responses

Transaction history returned successfully

Schema

Paginated list of virtual currency transactions for a profile.

dataarray of objectrequired
transaction_idstringrequired

Unique ID of the transaction.

transaction_typestringrequired

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

itemsarray of objectrequired

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.

operationstringrequired

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"

featurestringrequired

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

customer_placement_idstringrequired

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

reference_idstringrequired

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

is_sandboxbooleanrequired

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.

storestringrequired

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_idstringrequired

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

created_atstringrequired

When the transaction was recorded.

paginationobjectrequired
next_cursorstringrequired

Opaque cursor for the next page. Pass it as the cursor query parameter to fetch more results. Null when there are no more pages.

Example
{
  "data": [
    {
      "transaction_id": "0190e8a4-1c2b-7def-8abc-2c1a4b6d8e90",
      "transaction_type": "api_transaction",
      "items": [
        {
          "currency_code": "COINS",
          "amount": 500,
          "balance_after": 12950
        }
      ],
      "metadata": null,
      "operation": "reward",
      "feature": "daily_bonus",
      "customer_placement_id": "home-screen",
      "reference_id": null,
      "is_sandbox": false,
      "store": null,
      "store_transaction_id": null,
      "created_at": "2026-05-23T10:30:00Z"
    },
    {
      "transaction_id": "0190e7b2-9a44-7c10-bb31-7d2e9f0a1c55",
      "transaction_type": "store_purchase",
      "items": [
        {
          "currency_code": "COINS",
          "amount": 1000,
          "balance_after": 12450
        }
      ],
      "metadata": null,
      "operation": "top_up",
      "feature": null,
      "customer_placement_id": null,
      "reference_id": null,
      "is_sandbox": false,
      "store": "app_store",
      "store_transaction_id": "2000001218103228",
      "created_at": "2026-05-22T18:05:12Z"
    },
    {
      "transaction_id": "0190e5c0-3f18-7b9a-9e6d-44a1c8b27e03",
      "transaction_type": "subscription_renewal",
      "items": [
        {
          "currency_code": "GEMS",
          "amount": 200,
          "balance_after": 3280
        }
      ],
      "metadata": null,
      "operation": "top_up",
      "feature": null,
      "customer_placement_id": null,
      "reference_id": null,
      "is_sandbox": false,
      "store": "play_store",
      "store_transaction_id": "GPA.3345-1234-5678-90123",
      "created_at": "2026-05-20T09:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "MjAyNi0wNS0yMFQwOTowMDowMFowMTkwZTVjMC0zZjE4LTdiOWEtOWU2ZC00NGExYzhiMjdlMDM="
  }
}

Bad request. The error_code field identifies the cause:

  • validation_error — limit is outside 1–100, or neither adapty-profile-id nor adapty-customer-user-id is sent.
  • invalid_cursor — the cursor value can't be parsed.
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

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

Internal server error