---
title: "Upsert Player"
method: PUT
path: "/v1/players/{player_id}"
tags: ["Players"]
---

# Upsert Player

`PUT /v1/players/{player_id}`

Register the player or update them, and set the pricing context of their store.

`country` and `platform` are the only inputs the personalized store and the
order are priced with, so call this endpoint before reading the store for the
first time and whenever the player changes their country or their device.

## Path parameters

- `player_id` string, required

## Request body

- PlayerUpsert
  - `attributes` PlayerAttributes
    - `level` integer
    - `platform` 'any' | 'ios' | 'android' | 'other'
    - `marketplace` 'none' | 'app_store' | 'google_play' | 'aghanim' | 'other' | 'one_store' | 'galaxy_store'
    - `device_type` 'Apple' | 'Android' | 'Unknown' | 'Other'
    - `tags` PlayerTag[]
    - `soft_currency_amount` integer
    - `hard_currency_amount` integer
    - `appsflyer_id` string
    - `appsflyer_app_id` string
    - `appsflyer_meta` object
    - `appsflyer_event_params` object
    - `appsflyer_customer_user_id` string
    - `adjust_device_id` object
    - `adjust_adid` string
    - `adjust_app_token` string
    - `adjust_authorization_token` string
    - `adjust_purchase_event_token` string
    - `adjust_callback_params` object
    - `adjust_partner_params` object
    - `singular_device_id` object
    - `singular_app_id` string
    - `devtodev_appid` string
    - `devtodev_apikey` string
    - `devtodev_device_id` DevtodevDeviceId
      - `deviceId` string
      - `devtodevId` integer
      - `userId` string
      - `advertisingId` string
    - `tenjin_analytics_installation_id` string
    - `tenjin_advertising_id` string
    - `tenjin_developer_device_id` string
    - `tenjin_bundle_id` string
    - `tenjin_platform` string
    - `tenjin_os_version` string
    - `tenjin_app_version` string
    - `tenjin_os_version_release` string
    - `tenjin_build_id` string
    - `tenjin_device_model` string
    - `ga4_client_id` string — GA4 web `client_id` from the `_ga` cookie.
    - `ga4firebase_app_instance_id` string — Firebase mobile `app_instance_id` from the SDK.
    - `ga4_user_id` string — Partner-set GA4 cross-device `user_id`; falls back to `User.player_id` when unset.
  - `custom_attributes` object — The player's custom attributes.
  - `name` string — The player's name.
  - `avatar_url` string — The player's avatar URL.
  - `country` string, required — The two-letter country code (ISO 3166-1 alpha-2) of the player. It determines the price and the currency of the player's store.
  - `platform` 'any' | 'ios' | 'android' | 'other'
  - `email` string, email — The player's email address.
  - `user_agent` string — The User-Agent string of the player's browser. It is only used to derive the device type promotions are targeted by.

## Response `200`

Successful Response

- PlayerRead
  - `attributes` PlayerAttributes
    - `level` integer
    - `platform` 'any' | 'ios' | 'android' | 'other'
    - `marketplace` 'none' | 'app_store' | 'google_play' | 'aghanim' | 'other' | 'one_store' | 'galaxy_store'
    - `device_type` 'Apple' | 'Android' | 'Unknown' | 'Other'
    - `tags` PlayerTag[]
    - `soft_currency_amount` integer
    - `hard_currency_amount` integer
    - `appsflyer_id` string
    - `appsflyer_app_id` string
    - `appsflyer_meta` object
    - `appsflyer_event_params` object
    - `appsflyer_customer_user_id` string
    - `adjust_device_id` object
    - `adjust_adid` string
    - `adjust_app_token` string
    - `adjust_authorization_token` string
    - `adjust_purchase_event_token` string
    - `adjust_callback_params` object
    - `adjust_partner_params` object
    - `singular_device_id` object
    - `singular_app_id` string
    - `devtodev_appid` string
    - `devtodev_apikey` string
    - `devtodev_device_id` DevtodevDeviceId
      - `deviceId` string
      - `devtodevId` integer
      - `userId` string
      - `advertisingId` string
    - `tenjin_analytics_installation_id` string
    - `tenjin_advertising_id` string
    - `tenjin_developer_device_id` string
    - `tenjin_bundle_id` string
    - `tenjin_platform` string
    - `tenjin_os_version` string
    - `tenjin_app_version` string
    - `tenjin_os_version_release` string
    - `tenjin_build_id` string
    - `tenjin_device_model` string
    - `ga4_client_id` string — GA4 web `client_id` from the `_ga` cookie.
    - `ga4firebase_app_instance_id` string — Firebase mobile `app_instance_id` from the SDK.
    - `ga4_user_id` string — Partner-set GA4 cross-device `user_id`; falls back to `User.player_id` when unset.
  - `custom_attributes` object — The player's custom attributes.
  - `id` string, required — The unique identifier of the user.
  - `player_id` string, required — The unique player ID of the user.
  - `loyalty_points` integer — The amount of loyalty points the player has.

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-16** `6d6269f8cab6` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/aghanim/apis/aghanim-server-to-server-api/changes/v1/players/:player_id/put.md)

---

[API](https://skmtc.dev/aghanim/apis/aghanim-server-to-server-api.md) · [All operations](https://skmtc.dev/aghanim/apis/aghanim-server-to-server-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aghanim/apis/aghanim-server-to-server-api/revisions/6d6269f8cab6?raw)