Server Economy API Reference

PGOS provides a series of services to help you build a in-game economy, including virtual currencies, in-game items, stores, and inventory.

API List

API	Description
GrantItemToPlayer	Grant specified items to the player's inventory. The PGOS backend events event_item_granted/event_currency_changed will be triggered.
BatchRevokeInstances	Batch revoke the specified item instances in the player's inventory. The PGOS virtual server event event_item_revoked will be triggered.
GrantCurrencyToPlayer	Grant currency to player's balance. The PGOS backend event event_currency_changed will be triggered.
BatchGrantVirtualCurrenciesToPlayer	Batch grant virtual currencies to player's balance. NOTE: Premium currency can not be granted by this API.
SubtractPlayerCurrency	Subtract currency form player's balance. The PGOS backend event event_currency_changed will be triggered.
BatchSubtractPlayerVirtualCurrencies	Batch subtract virtual currencies from player's balance. NOTE: Premium currency can not be subtracted by this API.
GetPlayerBalance	Get player's balance.
GetPlayerInventory	Query item instances in the specified player's inventory.
GetPlayerInventoryWithFilter	Get all item instances in the player's inventory.
SetInstanceCustomData	Update the mutable_custom_data of the specified item instance in the player's inventory. The key must be prefixed with "int", "flt", or "str_", which respectively indicate that the value type is integer, float, or string. Instance mutable_custom_data can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).
BatchSetInstanceCustomData	Batch update the mutable_custom_data of the specified item instance in the player's inventory. The key must be prefixed with "int", "flt", or "str_", which respectively indicate that the value type is integer, float, or string. Instance mutable_custom_data can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).
SetInstanceCustomDataWithVersion	Update the mutable_custom_data of the specified item instance in the player's inventory. The key must be prefixed with "int", "flt", or "str_", which respectively indicate that the value type is integer, float, or string. The 'version' that needs to be passed in can be obtained from the mutable_custom_data of the ItemInstance. If the 'version' passed in is the latest, the callback will return success along with the latest data after updated. If the 'version' passed in is not the latest, the callback will return failure(err_code=11108, kBackendKVDataVersionMismatched (11108)) along with the current latest data, you may try again with the latest version. Instance mutable_custom_data can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).
IncrInstanceCustomData	Perform atomic increment operation on mutable_custom_data kvdata for the instance. [Only keys with the prefixes "int" and "flt" are supported]
SetInstanceTags	Update the tags data of the specified item instance in the player's inventory. Instance tags can have up to 32 keys, with each key limited to 128 bytes and each value limited to 1024 bytes(in a narrow-character string).
BatchSetInstanceTags	Batch update the tags data of the specified item instance in the player's inventory. Instance tags can have up to 32 keys, with each key limited to 128 bytes and each value limited to 1024 bytes(in a narrow-character string).

API Details

GrantItemToPlayer

Grant specified items to the player's inventory. The PGOS backend events event_item_granted/event_currency_changed will be triggered.

/**
 * Grant specified items to the player's inventory.
 * 
 * The PGOS backend events `event_item_granted`/`event_currency_changed` will be triggered.
 * 
 * @param Params Request params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void GrantItemToPlayer(
    const FPgosServerGrantItemToPlayerParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerGrantItemResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerGrantItemToPlayerParams&	Request params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerGrantItemResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

BatchRevokeInstances

Batch revoke the specified item instances in the player's inventory. The PGOS virtual server event event_item_revoked will be triggered.

/**
 * Batch revoke the specified item instances in the player's inventory.
 * 
 * The PGOS virtual server event `event_item_revoked` will be triggered.
 * 
 * @param Params Request params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void BatchRevokeInstances(
    const FPgosServerBatchRevokeInstancesParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerBatchRevokeInstancesResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerBatchRevokeInstancesParams&	Request params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerBatchRevokeInstancesResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

GrantCurrencyToPlayer

Grant currency to player's balance. The PGOS backend event event_currency_changed will be triggered.

/**
 * Grant currency to player's balance.
 * 
 * The PGOS backend event `event_currency_changed` will be triggered.
 * 
 * @param Params Request params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void GrantCurrencyToPlayer(
    const FPgosServerGrantCurrencyToPlayerParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerGrantCurrencyResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerGrantCurrencyToPlayerParams&	Request params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerGrantCurrencyResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

BatchGrantVirtualCurrenciesToPlayer

Batch grant virtual currencies to player's balance. NOTE: Premium currency can not be granted by this API.

/**
 * Batch grant virtual currencies to player's balance.
 * NOTE: Premium currency can not be granted by this API.
 * 
 * @param Params Result params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void BatchGrantVirtualCurrenciesToPlayer(
    const FPgosServerBatchGrantVirtualCurrenciesToPlayerParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerBatchGrantVirtualCurrenciesToPlayerResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerBatchGrantVirtualCurrenciesToPlayerParams&	Result params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerBatchGrantVirtualCurrenciesToPlayerResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

SubtractPlayerCurrency

Subtract currency form player's balance. The PGOS backend event event_currency_changed will be triggered.

/**
 * Subtract currency form player's balance.
 * The PGOS backend event `event_currency_changed` will be triggered.
 * 
 * @param Params Request params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void SubtractPlayerCurrency(
    const FPgosServerSubtractPlayerCurrencyParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerSubtractPlayerCurrencyResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerSubtractPlayerCurrencyParams&	Request params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerSubtractPlayerCurrencyResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

BatchSubtractPlayerVirtualCurrencies

Batch subtract virtual currencies from player's balance. NOTE: Premium currency can not be subtracted by this API.

/**
 * Batch subtract virtual currencies from player's balance.
 * NOTE: Premium currency can not be subtracted by this API.
 * 
 * @param Params Result params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void BatchSubtractPlayerVirtualCurrencies(
    const FPgosServerBatchSubtractPlayerVirtualCurrenciesParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerBatchSubtractPlayerVirtualCurrenciesResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerBatchSubtractPlayerVirtualCurrenciesParams&	Result params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerBatchSubtractPlayerVirtualCurrenciesResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

GetPlayerBalance

Get player's balance.

/**
 * Get player's balance.
 * 
 * @param Params Request params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void GetPlayerBalance(
    const FPgosServerGetPlayerBalanceParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerGetPlayerBalanceResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerGetPlayerBalanceParams&	Request params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerGetPlayerBalanceResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

GetPlayerInventory

Query item instances in the specified player's inventory.

/**
 * Query item instances in the specified player's inventory.
 * 
 * @param PlayerId The specified player id.
 * @param InstanceIds Item instance ids to query.  If the 'instance_ids' is empty, it will return all instances in the player's inventory.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void GetPlayerInventory(
    const FString& PlayerId,
    const TArray<FString>& InstanceIds,
    TFunction<void(const FPgosResult& Ret, const FPgosServerGetPlayerInventoryResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
PlayerId	const FString&	The specified player id.
InstanceIds	const TArray<FString>&	Item instance ids to query. If the 'instance_ids' is empty, it will return all instances in the player's inventory.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerGetPlayerInventoryResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

GetPlayerInventoryWithFilter

Get all item instances in the player's inventory.

/**
 * Get all item instances in the player's inventory.
 * 
 * @param Params Request params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void GetPlayerInventoryWithFilter(
    const FPgosServerGetPlayerInventoryWithFilterParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerGetPlayerInventoryWithFilterResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerGetPlayerInventoryWithFilterParams&	Request params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerGetPlayerInventoryWithFilterResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

SetInstanceCustomData

Update the mutable_custom_data of the specified item instance in the player's inventory. The key must be prefixed with "int", "flt", or "str_", which respectively indicate that the value type is integer, float, or string. Instance mutable_custom_data can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).

/**
 * Update the `mutable_custom_data` of the specified item instance in the player's inventory.
 * The key must be prefixed with "int_", "flt_", or "str_", which respectively indicate that the value type is integer, float, or string.
 * Instance `mutable_custom_data` can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).
 * 
 * @param Params Request params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void SetInstanceCustomData(
    const FPgosServerSetInstanceCustomDataParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerSetInstanceCustomDataResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerSetInstanceCustomDataParams&	Request params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerSetInstanceCustomDataResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

BatchSetInstanceCustomData

Batch update the mutable_custom_data of the specified item instance in the player's inventory. The key must be prefixed with "int", "flt", or "str_", which respectively indicate that the value type is integer, float, or string. Instance mutable_custom_data can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).

/**
 * Batch update the `mutable_custom_data` of the specified item instance in the player's inventory.
 * The key must be prefixed with "int_", "flt_", or "str_", which respectively indicate that the value type is integer, float, or string.
 * Instance `mutable_custom_data` can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).
 * 
 * @param Params Request params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void BatchSetInstanceCustomData(
    const FPgosServerBatchSetInstanceCustomDataParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerBatchSetInstanceCustomDataResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerBatchSetInstanceCustomDataParams&	Request params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerBatchSetInstanceCustomDataResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

SetInstanceCustomDataWithVersion

Update the mutable_custom_data of the specified item instance in the player's inventory. The key must be prefixed with "int", "flt", or "str_", which respectively indicate that the value type is integer, float, or string. The 'version' that needs to be passed in can be obtained from the mutable_custom_data of the ItemInstance. If the 'version' passed in is the latest, the callback will return success along with the latest data after updated. If the 'version' passed in is not the latest, the callback will return failure(err_code=11108, kBackendKVDataVersionMismatched (11108)) along with the current latest data, you may try again with the latest version. Instance mutable_custom_data can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).

/**
 * Update the `mutable_custom_data` of the specified item instance in the player's inventory.
 * The key must be prefixed with "int_", "flt_", or "str_", which respectively indicate that the value type is integer, float, or string.
 * The 'version' that needs to be passed in can be obtained from the `mutable_custom_data` of the `ItemInstance`.
 * If the 'version' passed in is the latest, the callback will return success along with the latest data after updated.
 * If the 'version' passed in is not the latest, the callback will return failure(err_code=11108, kBackendKVDataVersionMismatched (11108)) along with the current latest data, you may try again with the latest version.
 * Instance `mutable_custom_data` can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).
 * 
 * @param Params Request params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void SetInstanceCustomDataWithVersion(
    const FPgosServerSetInstanceCustomDataWithVersionParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerSetInstanceCustomDataResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerSetInstanceCustomDataWithVersionParams&	Request params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerSetInstanceCustomDataResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

IncrInstanceCustomData

Perform atomic increment operation on mutable_custom_data kvdata for the instance. [Only keys with the prefixes "int" and "flt" are supported]

/**
 * Perform atomic increment operation on `mutable_custom_data` kvdata for the instance. [Only keys with the prefixes "int_" and "flt_" are supported]
 * 
 * @param Params Request params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void IncrInstanceCustomData(
    const FPgosServerIncrInstanceCustomDataParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerIncrInstanceCustomDataResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerIncrInstanceCustomDataParams&	Request params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerIncrInstanceCustomDataResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

SetInstanceTags

Update the tags data of the specified item instance in the player's inventory. Instance tags can have up to 32 keys, with each key limited to 128 bytes and each value limited to 1024 bytes(in a narrow-character string).

/**
 * Update the `tags` data of the specified item instance in the player's inventory.
 * Instance `tags` can have up to 32 keys, with each key limited to 128 bytes and each value limited to 1024 bytes(in a narrow-character string).
 * 
 * @param Params Request params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void SetInstanceTags(
    const FPgosServerSetInstanceTagsParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerSetInstanceTagsResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerSetInstanceTagsParams&	Request params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerSetInstanceTagsResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

BatchSetInstanceTags

Batch update the tags data of the specified item instance in the player's inventory. Instance tags can have up to 32 keys, with each key limited to 128 bytes and each value limited to 1024 bytes(in a narrow-character string).

/**
 * Batch update the `tags` data of the specified item instance in the player's inventory.
 * Instance `tags` can have up to 32 keys, with each key limited to 128 bytes and each value limited to 1024 bytes(in a narrow-character string).
 * 
 * @param Params Request params.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void BatchSetInstanceTags(
    const FPgosServerBatchSetInstanceTagsParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosServerBatchSetInstanceTagsResult* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosServerBatchSetInstanceTagsParams&	Request params.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosServerBatchSetInstanceTagsResult* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void