Update User XP and Currency
POST
/v1/users/update-xp-currency
What this endpoint does
Quick start
identifier and at least one of xp or currency.Authentication and permission
manageUser. The key determines the community boundary.Complete examples
add, subtract, or overwrite with a finite non-negative value.Success and readback
200 USER_XP_CURRENCY_UPDATED response returns the resolved userId and supplied balances. Read back the same user with POST /v1/users/info; the persisted standard-currency field is named coins.Errors and recovery
USER_NOT_FOUND. Use a valid same-community key with manageUser for authentication or permission failures. The current deployment can return an unstructured HTML 500 for invalid bodies, including a missing mutation or an unknown updates field; fix the body and do not retry it unchanged.Retry safety
add or subtract can apply the mutation again. Read both balances before retrying an ambiguous result.Gotchas
updates object. When both balances are supplied, XP is written before currency, so an unclear outcome can be partial. The update response says currency; /v1/users/info says coins.Next steps
POST /v1/users/info with the returned platform userId to confirm saved XP and coins.Request
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location 'https://api.returning.ai/v1/users/update-xp-currency' \
--header 'Content-Type: application/json' \
--data '{
"identifier": {
"type": "platform_user_id",
"value": "12345"
},
"xp": {
"action": "add",
"value": 25
}
}'Response Response Example
200 - Success Example
{
"status": "success",
"code": "USER_XP_CURRENCY_UPDATED",
"message": "User XP and currency updated successfully",
"data": {
"userId": 12345,
"xp": 125,
"currency": 500
}
}Modified at 2026-07-30 06:52:28