A player movement is a timestamped record of one or more player metric values being updated. Every time your integration sends new metric data for a player — a deposit happened, a plan changed, a wager settled — Trackdesk stores that update as a movement and adjusts the player's running balance accordingly.
Movements are how you build a per-player history in Trackdesk. They are also what powers Player RevShare and any reporting that depends on knowing not just where a player ended up but how they got there.
For background, see Players in Trackdesk and Custom player metrics. For the dashboard-to-API mapping (Player ↔ client, Brand ↔ revenue_origin, Player movement ↔ client_metric_movement), see the iGaming glossary.
What a movement records
Each movement captures, atomically:
Which player the movement belongs to (resolved by external client ID + brand).
One or more metric updates — for each metric, the new value and whether it is absolute or relative.
The raw request payload as your integration sent it, stored as JSON for auditing.
An optional request ID for idempotency (the guarantee that retrying the same request will not apply the update twice).
A created at timestamp.
When the movement is processed, Trackdesk also updates the player's balance for each affected metric — a denormalised running total kept per player per metric so reports and revshare calculations don't have to re-aggregate the full movement history every time.
If the offer the player came in through has Player RevShare configured, Trackdesk also calculates this movement's revshare contribution at the same moment and stores it on the movement record, along with a reference to the settlement that ultimately pays it out. The recording API exposes both as total_revshare and account_settlement_id on each row of the movement listing response. See Player RevShare on offers for the full picture.
How movements are recorded
Movements are recorded by sending the update from your platform to the Trackdesk API. The request sends a payload that identifies the player and lists every metric update it wants to apply at once.
A movement payload includes:
External client ID — Your identifier for the player (1–255 characters). Required.
Revenue origin ID — The UUID of the brand the player belongs to (for example "Acme Casino"). Required.
Metrics — A list of up to 20 metric updates per movement. Each entry has:
The metric code exactly as defined on your workspace's metrics page.
A value type — either absolute or relative (see below).
A value as a numeric string — for example
10,-1.5,0.001.
Request ID — An optional identifier for safe retries (1–100 characters). See "Idempotent retries" below.
The player must already exist before a movement can be recorded against them. The tracking endpoint does not auto-create players; if no player matches the external ID + brand pair, the API rejects the call with client not found. See Players in Trackdesk for how players are registered.
Absolute versus relative values
Every metric update in a movement is either absolute or relative. The choice is per metric per movement, so a single movement can mix both.
Absolute — The value replaces the current balance for that metric. Use absolute when your integration always knows the latest total — for example, "the player's plan tier is now
3", or "the player's lifetime deposits are now1240.50".Relative (sometimes called a delta or incremental value) — The value is added to the current balance (use a negative value to subtract). Use relative when your integration is reporting an event in isolation — for example, "the player just deposited
50", or "refund of-10processed". Trackdesk takes care of aggregating these per-event deltas into the running balance for you.
Picking the right type matters: a relative 50 sent twice changes the balance by 100; an absolute 50 sent twice leaves the balance at 50. Make sure your integration is consistent per metric — mixing absolute and relative writes for the same metric without coordination will give you a balance that does not match what your platform thinks it should be.
Idempotent retries with request ID
Network errors happen, and an integration that retries a failed movement should not end up applying the same update twice. The optional request ID field exists for exactly this case.
When your integration includes a request ID (1–100 characters) on a movement:
If no movement with that request ID has been recorded for the player yet, the movement is processed normally.
If a movement with the same request ID already exists for the player, Trackdesk rejects the duplicate so the balance is not touched a second time. The API returns the error
duplicate metric movement request.
The request ID is unique per player. Use a value your integration can reliably regenerate on retry — for example, the underlying transaction or event ID from your own system.
Viewing the movement log
All recorded movements are visible in the dashboard at Players → Player movements. The page shows one row per movement, with columns for the player, every defined metric, and the timestamp.
Above the table are two controls:
A date range picker — defaults to the last 7 days. Use the presets or pick a custom range.
A Filter button that opens a sidebar with three additional filters:
Player ID — Trackdesk's internal player UUID.
External client ID — The identifier your platform uses for the player.
Request ID — Useful for tracing a specific integration retry or event.
Inspecting a single movement
Click any row in the movement log to open the Movement detail sidebar. It contains two sections:
Movement detail — A vertical breakdown of every column on the row, including all metric values for that movement.
Raw payload — The exact JSON your integration sent, formatted and syntax-highlighted. This is the source of truth for what was received and is the right place to look when a value on a player doesn't match what your platform expected.
When a movement doesn't appear
If your integration sent a movement but it isn't showing up in the log:
Check the date range — the default is only the last 7 days.
Make sure the player exists — movements require a registered player. If no matching external ID + brand pair is found, the API returns
client not foundand the movement is not recorded.If your integration is retrying with a fixed request ID, the second attempt is rejected with
duplicate metric movement request— only the first call recorded the movement.Confirm that every metric code in the payload exactly matches a code defined on your workspace's metrics page — codes are case-sensitive and must use the kebab-case format.