PATCH/PUT /v1/users/:userId/characters/:characterId/wallet

The wallet endpoints let administrators adjust a character’s in-game currency balance. There are two distinct operations depending on the HTTP method you use:

PATCH — Sets the wallet’s balance field to an exact absolute value you specify. Use this to correct or override a balance directly.
PUT — Applies a transaction by adding (or subtracting) an amount to the current balance. Use this for incremental adjustments such as paying out rewards or deducting fines.

Both operations require the ADMINISTRATOR permission. If the character does not yet have a wallet, PATCH creates one before applying the update.

Both PATCH and PUT require the ADMINISTRATOR permission. Regular users cannot call these endpoints.

Both endpoints only work on characters with an idStatus of approved. Attempting to update the wallet of an unapproved character returns 403.

Endpoint

PATCH https://api.cacolombia.com/v1/users/:userId/characters/:characterId/wallet
PUT   https://api.cacolombia.com/v1/users/:userId/characters/:characterId/wallet

Path Parameters

string

required

The Snowflake ID of the user account that owns the character.

string

required

The Snowflake ID of the character whose wallet you want to update.

Request Body — PATCH

number

required

The new absolute balance to assign to the wallet. The current balance is overwritten entirely with this value.

Request Body — PUT

number

required

The amount to add to the current wallet balance. Use a positive number to credit the character and a negative number to debit them.

Response

Both methods return 200 OK with the updated wallet object on success:

string

The Snowflake ID of the character this wallet belongs to.

number

The wallet’s balance after the update has been applied.

string

ISO 8601 timestamp of when the wallet was first created.

string

ISO 8601 timestamp of when the wallet was last modified (reflects this update).

Example Requests

PATCH — Set absolute balance

curl -X PATCH "https://api.cacolombia.com/v1/users/112233445566778899/characters/998877665544332211/wallet" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"balance": 20000}'

PUT — Apply transaction amount

curl -X PUT "https://api.cacolombia.com/v1/users/112233445566778899/characters/998877665544332211/wallet" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000}'

Example Response

{
  "characterId": "998877665544332211",
  "balance": 20000,
  "createdAt": "2024-03-15T10:00:00.000Z",
  "updatedAt": "2024-06-02T09:15:44.000Z"
}

Error Responses

Status	Description
`400`	The request body is missing required fields or contains values of the wrong type (e.g., a string instead of a number).
`401`	You are not authenticated. Provide a valid authorization token with your request.
`403`	Your account does not hold the `ADMINISTRATOR` permission.
`403`	The target character’s `idStatus` is not `approved`. Only approved characters have active wallets.
`404`	No user was found for the given `userId`.
`404`	No character was found for the given `characterId` under that user.

Overview

Auth & OAuth

Users

Characters

Economy

Banking

Staff

Utilities

PATCH/PUT /v1/users/:userId/characters/:characterId/wallet

Endpoint

Path Parameters

Request Body — PATCH

Request Body — PUT

Response

Example Requests

Example Response

Error Responses

​Endpoint

​Path Parameters

​Request Body — PATCH

​Request Body — PUT

​Response

​Example Requests

​Example Response

​Error Responses

Endpoint

Path Parameters

Request Body — PATCH

Request Body — PUT

Response

Example Requests

Example Response

Error Responses