Documentation

​
​

Development

User Acquisition

Monetization

Industry

Economy API

v2

Supported
​

Economy API

v2

Supported
​
Unity Services Web APIs
​
​
Economy API
  • Introduction
  • Concepts
Endpoints
  • Configuration
  • Currencies
  • Inventory
  • Purchases

Economy API

Introduction

This document outlines the API specification for the Economy API. The Economy service allows the game client to retrieve and modify a player's economy resources in the cloud.

Concepts

Resources

Economy currently allows interaction with the following types of resources:
  • Currencies: A resource that, when defined, contains two parameters: Initial and Max. The Initial parameter determines how much of the currency a game assigns to a player upon first interacting with the Economy system. The Max parameter determines how much of the currency the player is allowed to have.
  • Inventory Items: A resource that doesn't have any set parameters; its intended use is to indicate the ownership or acquisition of an item in-game, for example, Sword and Shield. A game client can add, remove or update the associated data of an instance of a configured inventory item from the player's inventory.
  • Virtual Purchases: A transactional resource to implement a shop or trade feature. Allows the player to buy items/currencies using the previously defined currencies or inventory items. A game client can redeem a virtual purchase and the player's account updates with the rewards if the costs criteria are met.
  • Real Money Purchases: A transactional resource with the intended use to facilitate a shop or trade feature. Allows the player to buy any amount of items/currencies through an in-app purchase. Only uses the previously defined currencies or inventory items. A game client can redeem a real money purchase and the player's account updates with the rewards.
The above resources also have an optional Custom Data parameter that can be populated with JSON data from the dashboard to allow clients to read bespoke data.

Writelock

The WriteLock is an integer that is automatically incremented serverside whenever a request that changes the stored value of a player's account or inventory. The purpose of the WriteLock is to help prevent requests from the same or other game clients happening out-of-sync. This parameter is optional, but when supplied with a request, the service does a comparison with the stored WriteLock on the server, and returns an error on mismatch.

Rate Limits

The API has rate limiting in place. Requests are limited on a per-player basis up to 150 requests per minute. The API responds with a 
429
HTTP status code if the requests exceed the rate limit. Responses with a 
429
status code include a 
Retry-After
header to be used in conjunction with a client's retry logic, the value is the number of seconds until a request for the given player is accepted.
Download OpenAPI specification:

Player currency balances

Get a list of currency balances for a player. Results ordered in ascending currency ID.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "Player currency balances"

projectId

string
required
ID of the project.

playerId

string
required
ID of the player.

Header parameters for "Player currency balances"

unity-installation-id

string
Unique identifier that identifies an installation on the client’s device. The same player can have different installationIds if they have the game installed on different devices. It is available to all Unity packages that integrate with the Services SDK Core package.

analytics-user-id

string
A unique string that identifies the player and is consistent across their subsequent play sessions for analytics purposes. It is the primary user identifier and it comes from the Core package.

Query parameters for "Player currency balances"

configAssignmentHash

string
Configuration assignment hash that should be used when processing this request.

after

string
The currency ID after which to retrieve the next page of balances.

limit

integer
Number of currencies to be returned. Defaults to 20.

HTTP response status codes for "Player currency balances":

Code samples for "Player currency balances":

Request example

curl -X GET \ -H "unity-installation-id: <unity-installation-id>" \ -H "analytics-user-id: <analytics-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://economy.services.api.unity.com/v2/projects/{projectId}/players/{playerId}/currencies"

Response example

{ "results": [ { "currencyId": "string", "balance": 0, "writeLock": "string", "created": { "date": "2020-04-01T13:07:23Z" }, "modified": { "date": "2020-04-01T13:07:23Z" } } ], "links": { "next": "string" }}

Set currency balance

Set a player's currency balance.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "Set currency balance"

projectId

string
required
ID of the project.

playerId

string
required
ID of the player.

currencyId

string
required
Resource ID of the currency.

Header parameters for "Set currency balance"

unity-installation-id

string
Unique identifier that identifies an installation on the client’s device. The same player can have different installationIds if they have the game installed on different devices. It is available to all Unity packages that integrate with the Services SDK Core package.

analytics-user-id

string
A unique string that identifies the player and is consistent across their subsequent play sessions for analytics purposes. It is the primary user identifier and it comes from the Core package.

Query parameters for "Set currency balance"

configAssignmentHash

string
Configuration assignment hash that should be used when processing this request.

Request body for "Set currency balance"

Media Type:
application/json

currencyId

string
deprecated
Resource ID of the currency.

balance

integer
required
The player's balance.

writeLock

string
The write lock for the currency balance.

HTTP response status codes for "Set currency balance":

Code samples for "Set currency balance":

Request example

curl -X PUT \ -H "unity-installation-id: <unity-installation-id>" \ -H "analytics-user-id: <analytics-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "currencyId": "string", "balance": 0, "writeLock": "string"}' \ "https://economy.services.api.unity.com/v2/projects/{projectId}/players/{playerId}/currencies/{currencyId}"

Response example

{ "currencyId": "string", "balance": 0, "writeLock": "string", "created": { "date": "2020-04-01T13:07:23Z" }, "modified": { "date": "2020-04-01T13:07:23Z" }}

Increment currency balance

Increment a player's currency balance by a given value.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "Increment currency balance"

projectId

string
required
ID of the project.

playerId

string
required
ID of the player.

currencyId

string
required
Resource ID of the currency.

Header parameters for "Increment currency balance"

unity-installation-id

string
Unique identifier that identifies an installation on the client’s device. The same player can have different installationIds if they have the game installed on different devices. It is available to all Unity packages that integrate with the Services SDK Core package.

analytics-user-id

string
A unique string that identifies the player and is consistent across their subsequent play sessions for analytics purposes. It is the primary user identifier and it comes from the Core package.

Query parameters for "Increment currency balance"

configAssignmentHash

string
Configuration assignment hash that should be used when processing this request.

Request body for "Increment currency balance"

Media Type:
application/json

currencyId

string
deprecated
Resource ID of the currency.

amount

integer
required
The value by which to increment or decrement. Zero is allowed but results in no change to the currency balance.

writeLock

string
The write lock for the currency balance.

HTTP response status codes for "Increment currency balance":

Code samples for "Increment currency balance":

Request example

curl -X POST \ -H "unity-installation-id: <unity-installation-id>" \ -H "analytics-user-id: <analytics-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "currencyId": "string", "amount": 0, "writeLock": "string"}' \ "https://economy.services.api.unity.com/v2/projects/{projectId}/players/{playerId}/currencies/{currencyId}/increment"

Response example

{ "currencyId": "string", "balance": 0, "writeLock": "string", "created": { "date": "2020-04-01T13:07:23Z" }, "modified": { "date": "2020-04-01T13:07:23Z" }}

Decrement currency balance

Decrements a player's currency balance by a given value.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "Decrement currency balance"

projectId

string
required
ID of the project.

playerId

string
required
ID of the player.

currencyId

string
required
Resource ID of the currency.

Header parameters for "Decrement currency balance"

unity-installation-id

string
Unique identifier that identifies an installation on the client’s device. The same player can have different installationIds if they have the game installed on different devices. It is available to all Unity packages that integrate with the Services SDK Core package.

analytics-user-id

string
A unique string that identifies the player and is consistent across their subsequent play sessions for analytics purposes. It is the primary user identifier and it comes from the Core package.

Query parameters for "Decrement currency balance"

configAssignmentHash

string
Configuration assignment hash that should be used when processing this request.

Request body for "Decrement currency balance"

Media Type:
application/json

currencyId

string
deprecated
Resource ID of the currency.

amount

integer
required
The value by which to increment or decrement. Zero is allowed but results in no change to the currency balance.

writeLock

string
The write lock for the currency balance.

HTTP response status codes for "Decrement currency balance":

Code samples for "Decrement currency balance":

Request example

curl -X POST \ -H "unity-installation-id: <unity-installation-id>" \ -H "analytics-user-id: <analytics-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "currencyId": "string", "amount": 0, "writeLock": "string"}' \ "https://economy.services.api.unity.com/v2/projects/{projectId}/players/{playerId}/currencies/{currencyId}/decrement"

Response example

{ "currencyId": "string", "balance": 0, "writeLock": "string", "created": { "date": "2020-04-01T13:07:23Z" }, "modified": { "date": "2020-04-01T13:07:23Z" }}

Add inventory item

Add an item to a player's inventory.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "Add inventory item"

projectId

string
required
ID of the project.

playerId

string
required
ID of the player.

Header parameters for "Add inventory item"

unity-installation-id

string
Unique identifier that identifies an installation on the client’s device. The same player can have different installationIds if they have the game installed on different devices. It is available to all Unity packages that integrate with the Services SDK Core package.

analytics-user-id

string
A unique string that identifies the player and is consistent across their subsequent play sessions for analytics purposes. It is the primary user identifier and it comes from the Core package.

Query parameters for "Add inventory item"

configAssignmentHash

string
Configuration assignment hash that should be used when processing this request.

Request body for "Add inventory item"

Media Type:
application/json

inventoryItemId

string
required
Resource ID of the inventory item.

playersInventoryItemId

string
A 
playersInventoryItemId
for the item being created. If not given, Economy automatically generates the ID. An ID must be unique for a player.

instanceData

object
Instance data to be saved against the new inventory item. Max size when serialized 5 KB.

HTTP response status codes for "Add inventory item":

Code samples for "Add inventory item":

Request example

curl -X POST \ -H "unity-installation-id: <unity-installation-id>" \ -H "analytics-user-id: <analytics-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "inventoryItemId": "string", "playersInventoryItemId": "string", "instanceData": {}}' \ "https://economy.services.api.unity.com/v2/projects/{projectId}/players/{playerId}/inventory"

Response example

{ "playersInventoryItemId": "string", "inventoryItemId": "string", "instanceData": {}, "writeLock": "string", "created": { "date": "2020-04-01T13:07:23Z" }, "modified": { "date": "2020-04-01T13:07:23Z" }}

List player inventory

Get a list of inventory for a player. Results ordered by ascending 
playersInventoryItemId
. 
playersIventoryItemIds
and 
inventoryItemIds
filters are optional, if not given all items will be returned. If both are given an item must match both to be returned.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "List player inventory"

projectId

string
required
ID of the project.

playerId

string
required
ID of the player.

Header parameters for "List player inventory"

unity-installation-id

string
Unique identifier that identifies an installation on the client’s device. The same player can have different installationIds if they have the game installed on different devices. It is available to all Unity packages that integrate with the Services SDK Core package.

analytics-user-id

string
A unique string that identifies the player and is consistent across their subsequent play sessions for analytics purposes. It is the primary user identifier and it comes from the Core package.

Query parameters for "List player inventory"

configAssignmentHash

string
Configuration assignment hash that should be used when processing this request.

after

string
The 
playersInventoryItemId
after which to retrieve the next page of balances.

limit

integer
Number of items to be returned. Defaults to 20.

playersInventoryItemIds

array
List of 
playersInventoryItemIds
in array notation, for example, 
playersInventoryItemIds[]=ID1&playersInventoryItemIds[]=ID2
.

inventoryItemIds

array
List of inventory item IDs in array notation, for example, 
inventoryItemIds[]=ID1&inventoryItemIds[]=ID2
.

HTTP response status codes for "List player inventory":

Code samples for "List player inventory":

Request example

curl -X GET \ -H "unity-installation-id: <unity-installation-id>" \ -H "analytics-user-id: <analytics-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://economy.services.api.unity.com/v2/projects/{projectId}/players/{playerId}/inventory"

Response example

{ "results": [ { "playersInventoryItemId": "string", "inventoryItemId": "string", "instanceData": {}, "writeLock": "string", "created": { "date": "2020-04-01T13:07:23Z" }, "modified": { "date": "2020-04-01T13:07:23Z" } } ], "links": { "next": "string" }}

Update player's inventory item

Update a player's inventory item.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "Update player's inventory item"

projectId

string
required
ID of the project.

playerId

string
required
ID of the player.

playersInventoryItemId

string
required
The 
playersInventoryItemId
of the item to be updated.

Header parameters for "Update player's inventory item"

unity-installation-id

string
Unique identifier that identifies an installation on the client’s device. The same player can have different installationIds if they have the game installed on different devices. It is available to all Unity packages that integrate with the Services SDK Core package.

analytics-user-id

string
A unique string that identifies the player and is consistent across their subsequent play sessions for analytics purposes. It is the primary user identifier and it comes from the Core package.

Query parameters for "Update player's inventory item"

configAssignmentHash

string
Configuration assignment hash that should be used when processing this request.

Request body for "Update player's inventory item"

Media Type:
application/json

instanceData

object
required
Instance data to be saved against the inventory item. Max size when serialized 5 KB.

writeLock

string
The write lock for the inventory item instance.

HTTP response status codes for "Update player's inventory item":

Code samples for "Update player's inventory item":

Request example

curl -X PUT \ -H "unity-installation-id: <unity-installation-id>" \ -H "analytics-user-id: <analytics-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "instanceData": {}, "writeLock": "string"}' \ "https://economy.services.api.unity.com/v2/projects/{projectId}/players/{playerId}/inventory/{playersInventoryItemId}"

Response example

{ "playersInventoryItemId": "string", "inventoryItemId": "string", "instanceData": {}, "writeLock": "string", "created": { "date": "2020-04-01T13:07:23Z" }, "modified": { "date": "2020-04-01T13:07:23Z" }}

Delete player's inventory item

Delete a player's inventory item.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "Delete player's inventory item"

projectId

string
required
ID of the project.

playerId

string
required
ID of the player.

playersInventoryItemId

string
required
The 
playersInventoryItemId
of the item to be updated.

Header parameters for "Delete player's inventory item"

unity-installation-id

string
Unique identifier that identifies an installation on the client’s device. The same player can have different installationIds if they have the game installed on different devices. It is available to all Unity packages that integrate with the Services SDK Core package.

analytics-user-id

string
A unique string that identifies the player and is consistent across their subsequent play sessions for analytics purposes. It is the primary user identifier and it comes from the Core package.

Query parameters for "Delete player's inventory item"

configAssignmentHash

string
Configuration assignment hash that should be used when processing this request.

writeLock

string
The writelock for a database entry.

Request body for "Delete player's inventory item"

Media Type:
application/json

writeLock

string
deprecated
The write lock for the inventory item instance. This property has been deprecated. Please use the 
writeLock
query parameter instead.

HTTP response status codes for "Delete player's inventory item":

Code samples for "Delete player's inventory item":

Request example

curl -X DELETE \ -H "unity-installation-id: <unity-installation-id>" \ -H "analytics-user-id: <analytics-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "writeLock": "string"}' \ "https://economy.services.api.unity.com/v2/projects/{projectId}/players/{playerId}/inventory/{playersInventoryItemId}"

Response example

{ "type": "string", "title": "string", "status": 0, "code": 0, "detail": "string", "instance": "string", "details": [ {} ]}

Make virtual purchase

Make a virtual purchase for a player.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "Make virtual purchase"

projectId

string
required
ID of the project.

playerId

string
required
ID of the player.

Header parameters for "Make virtual purchase"

unity-installation-id

string
Unique identifier that identifies an installation on the client’s device. The same player can have different installationIds if they have the game installed on different devices. It is available to all Unity packages that integrate with the Services SDK Core package.

analytics-user-id

string
A unique string that identifies the player and is consistent across their subsequent play sessions for analytics purposes. It is the primary user identifier and it comes from the Core package.

Query parameters for "Make virtual purchase"

configAssignmentHash

string
Configuration assignment hash that should be used when processing this request.

Request body for "Make virtual purchase"

Media Type:
application/json

id

string
required
ID of the purchase.

playersInventoryItemIds

array[string]
IDs of the player's inventory items that should be used for any item costs associated with the purchase.

HTTP response status codes for "Make virtual purchase":

Code samples for "Make virtual purchase":

Request example

curl -X POST \ -H "unity-installation-id: <unity-installation-id>" \ -H "analytics-user-id: <analytics-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "id": "string", "playersInventoryItemIds": [ "string" ]}' \ "https://economy.services.api.unity.com/v2/projects/{projectId}/players/{playerId}/purchases/virtual"

Response example

{ "costs": { "currency": [], "inventory": [] }, "rewards": { "currency": [], "inventory": [] }}

Redeem Apple App Store purchase

Redeem an Apple App Store purchase for a player.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "Redeem Apple App Store purchase"

projectId

string
required
ID of the project.

playerId

string
required
ID of the player.

Header parameters for "Redeem Apple App Store purchase"

unity-installation-id

string
Unique identifier that identifies an installation on the client’s device. The same player can have different installationIds if they have the game installed on different devices. It is available to all Unity packages that integrate with the Services SDK Core package.

analytics-user-id

string
A unique string that identifies the player and is consistent across their subsequent play sessions for analytics purposes. It is the primary user identifier and it comes from the Core package.

Query parameters for "Redeem Apple App Store purchase"

configAssignmentHash

string
Configuration assignment hash that should be used when processing this request.

Request body for "Redeem Apple App Store purchase"

Media Type:
application/json

id

string
required
ID of the purchase.

receipt

string
required
Receipt data returned from the Apple App Store as a result of a successful purchase. This should be base64 encoded.

localCost

integer
required
The cost of the purchase as an integer in the minor currency format, for example, $1.99 USD would be 199.

localCurrency

string
required
example: USD
The ISO-4217 currency code with which the player purchased the IAP.

HTTP response status codes for "Redeem Apple App Store purchase":

Code samples for "Redeem Apple App Store purchase":

Request example

curl -X POST \ -H "unity-installation-id: <unity-installation-id>" \ -H "analytics-user-id: <analytics-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "id": "string", "receipt": "string", "localCost": 0, "localCurrency": "USD"}' \ "https://economy.services.api.unity.com/v2/projects/{projectId}/players/{playerId}/purchases/appleappstore"

Response example

{ "verification": { "status": "VALID", "store": { "code": "string", "message": "string", "receipt": "string" } }, "rewards": { "currency": [], "inventory": [] }}

Redeem Google Play purchase

Redeem a Google Play store purchase for a player.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "Redeem Google Play purchase"

projectId

string
required
ID of the project.

playerId

string
required
ID of the player.

Header parameters for "Redeem Google Play purchase"

unity-installation-id

string
Unique identifier that identifies an installation on the client’s device. The same player can have different installationIds if they have the game installed on different devices. It is available to all Unity packages that integrate with the Services SDK Core package.

analytics-user-id

string
A unique string that identifies the player and is consistent across their subsequent play sessions for analytics purposes. It is the primary user identifier and it comes from the Core package.

Query parameters for "Redeem Google Play purchase"

configAssignmentHash

string
Configuration assignment hash that should be used when processing this request.

Request body for "Redeem Google Play purchase"

Media Type:
application/json

id

string
required
ID of the purchase.

purchaseData

string
required
A JSON encoded string returned from a successful in-app billing purchase.

purchaseDataSignature

string
required
A signature of the 
purchaseData
returned from a successful in-app billing purchase.

localCost

integer
required
The cost of the purchase as an integer in the minor currency format, for example, $1.99 USD would be 199.

localCurrency

string
required
example: USD
The ISO-4217 currency code with which the player purchased the IAP.

HTTP response status codes for "Redeem Google Play purchase":

Code samples for "Redeem Google Play purchase":

Request example

curl -X POST \ -H "unity-installation-id: <unity-installation-id>" \ -H "analytics-user-id: <analytics-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "id": "string", "purchaseData": "string", "purchaseDataSignature": "string", "localCost": 0, "localCurrency": "USD"}' \ "https://economy.services.api.unity.com/v2/projects/{projectId}/players/{playerId}/purchases/googleplaystore"

Response example

{ "verification": { "status": "VALID", "store": { "receipt": "string" } }, "rewards": { "currency": [], "inventory": [] }}

Get player's configuration

Returns the economy configuration for the player with any overrides applied.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "Get player's configuration"

projectId

string
required
ID of the project.

playerId

string
required
ID of the player.

Header parameters for "Get player's configuration"

unity-installation-id

string
Unique identifier that identifies an installation on the client’s device. The same player can have different installationIds if they have the game installed on different devices. It is available to all Unity packages that integrate with the Services SDK Core package.

analytics-user-id

string
A unique string that identifies the player and is consistent across their subsequent play sessions for analytics purposes. It is the primary user identifier and it comes from the Core package.

Query parameters for "Get player's configuration"

configAssignmentHash

string
Configuration assignment hash that should be used when processing this request.

HTTP response status codes for "Get player's configuration":

Code samples for "Get player's configuration":

Request example

curl -X GET \ -H "unity-installation-id: <unity-installation-id>" \ -H "analytics-user-id: <analytics-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://economy.services.api.unity.com/v2/projects/{projectId}/players/{playerId}/config/resources"

Response example

{ "metadata": { "configAssignmentHash": "string" }, "results": [ { "id": "string", "name": "string", "type": "CURRENCY", "created": { "date": "2020-04-01T13:07:23Z" }, "modified": { "date": "2020-04-01T13:07:23Z" }, "initial": 0, "max": 0, "customData": {} } ]}
Copyright © 2026 Unity Technologies
LegalPrivacy PolicyCookiesDocumentation Terms of UseDo Not Sell or Share My Personal InformationYour Privacy Choices (Cookie Settings)

"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S and elsewhere (more info here). Other names or brands are trademarks of their respective owners.

Some pages are machine-translated for convenience, and may contain inaccuracies. In the event of conflicting information, the English version is authoritative.