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

列出虚拟货币交易记录

返回用户画像的虚拟货币交易历史记录,按最新优先排序。结果使用游标分页:当响应中包含非空的 pagination.next_cursor 时,将其作为 cursor 查询参数传回以获取下一页。

Query parameters

currency_codestring

将历史记录筛选为单一虚拟货币代码。

cursorstring

在上一次响应中作为 pagination.next_cursor 返回的不透明分页游标。省略此参数以获取第一页。

limitinteger

每页返回的最大交易数量。默认为 50。

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 二者必填其一。

Responses

交易历史记录返回成功

Schema

用户画像的虚拟货币交易记录分页列表。

dataarray of objectrequired
transaction_idstringrequired

交易的唯一 ID。

transaction_typestringrequired

交易来源。可选值为 store_purchase、subscription_renewal、trial_start、api_transaction、dashboard_transaction、refund 或 expiry。

itemsarray of objectrequired

此次交易中记录的各币种余额变动。

currency_codestringrequired

虚拟货币代码。

amountintegerrequired

应用于余额的带符号变动量。正值为充值,负值为扣除。

balance_afterintegerrequired

本次交易应用后的货币余额。

metadataobject

与交易一同存储的键值对(如有)。

operationstringrequired

交易所代表的操作类型。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"

featurestringrequired

您传入的币种消费用途或发放原因。由 Adapty 创建的交易上该值为 null。

customer_placement_idstringrequired

您传入的应用内页面或版位 ID。由 Adapty 创建的交易上该值为 null。

reference_idstringrequired

您传入的系统中相关对象的 ID。由 Adapty 创建的交易上该值为 null。

is_sandboxbooleanrequired

该交易是否为测试交易。对于由 Adapty 创建的交易,该值与对应商店购买的环境保持一致。对于 api_transaction,该值为您传入的值,默认为 false。

storestringrequired

相关购买所在的商店。在 Adapty 根据商店事件(购买、续订、试用、退款)创建的交易以及携带购买引用的 api_transaction 上会设置该字段。

store_transaction_idstringrequired

相关购买的商店交易 ID。与 store 字段在相同交易上设置。

created_atstringrequired

交易记录的时间。

paginationobjectrequired
next_cursorstringrequired

下一页的不透明游标。将其作为 cursor 查询参数传递以获取更多结果。当没有更多页面时为 Null。

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="
  }
}

请求无效。error_code 字段标识原因:

  • validation_error — limit 超出 1–100 范围,或未发送 adapty-profile-id 也未发送 adapty-customer-user-id。
  • invalid_cursor — cursor 值无法解析。
Schema
errorsarray of objectrequired
sourcestring

错误来源

errorsarray of string

错误消息数组

error_codestringrequired

简短错误名称

status_codeintegerrequired

HTTP 状态码

未授权。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 状态码

服务器内部错误