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 HTTP status code if the requests exceed the rate limit.
Responses with a status code include a 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.
429429Retry-AfterDownload 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
Code samples for "{title}":
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
Code samples for "{title}":
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
Code samples for "{title}":
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
Code samples for "{title}":
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
Code samples for "{title}":
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 .
and filters are optional, if not given all items will be returned. If both are given an item must match both to be returned.
playersInventoryItemIdplayersIventoryItemIdsinventoryItemIdsAuthorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
Code samples for "{title}":
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
Code samples for "{title}":
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
Code samples for "{title}":
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
Code samples for "{title}":
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
Code samples for "{title}":
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
Code samples for "{title}":
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
Code samples for "{title}":
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": {} } ]}