Get Balance

Warning

Testing Phase: This endpoint is currently in testing and not ready for production. API structure and responses may change.

This method retrieves the current gamification coins balance for a player. Use gateway.[msdomain]

Request (GET)

`/gateway/coins/balance/{version}/{brand_id}`

Parameters:

Name	In	Type	Required	Description
version	path	string	true	The API version to use.
brand_id	path	int	true	Brand identifier
x-auth-token	header	string	true	Player authentication token (extracted from request header)

Note: The player_id is automatically extracted from the x-auth-token header by the gateway and appended to the path when forwarding to the marketing service.

Response

Status 200

{
  "status": "success",
  "data": {
    "brand_id": 1001,
    "player_id": 12345,
    "current_balance": "250.50",
    "total_received": "500.00",
    "total_redeemed": "249.50",
    "total_items_redeemed": 5,
    "average_item_cost": "49.90",
    "updated_at": "2025-01-09 14:30:00"
  }
}

Response Fields:

Field	Type	Description
brand_id	int	Brand identifier
player_id	int	Player identifier
current_balance	string	Current available coins balance (decimal)
total_received	string	Total coins received since account creation (decimal)
total_redeemed	string	Total coins redeemed since account creation (decimal)
total_items_redeemed	int	Total number of shop items the player has redeemed (lifetime count)
average_item_cost	string	Average coin cost per redeemed item (total_redeemed / total_items_redeemed). Returns “0” if no items redeemed.
updated_at	string	Last balance update timestamp (format: YYYY-MM-DD HH:MM:SS)

Status 500

{
  "status": "error",
  "data": null,
  "message": "Failed to get player balance"
}