ドキュメント

​
​

Development

User Acquisition

Monetization

産業

Economy API

v2

サポート対象
​

Economy API

v2

サポート対象
​

このページは選択した言語では使用できません。
Unity Services Web APIs
​
​
Economy API
  • Introduction
  • Concepts
mdx:openapi: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 "{title}"

projectId

string
必須
ID of the project.

playerId

string
必須
ID of the player.

Header parameters for "{title}"

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 "{title}"

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 "{title}":

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

Path parameters for "{title}"

projectId

string
必須
ID of the project.

playerId

string
必須
ID of the player.

currencyId

string
必須
Resource ID of the currency.

Header parameters for "{title}"

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 "{title}"

configAssignmentHash

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

Request body for "{title}"

Media Type:
application/json

currencyId

string
deprecated
Resource ID of the currency.

balance

integer
必須
The player's balance.

writeLock

string
The write lock for the currency balance.

HTTP response status codes for "{title}":

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

Path parameters for "{title}"

projectId

string
必須
ID of the project.

playerId

string
必須
ID of the player.

currencyId

string
必須
Resource ID of the currency.

Header parameters for "{title}"

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 "{title}"

configAssignmentHash

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

Request body for "{title}"

Media Type:
application/json

currencyId

string
deprecated
Resource ID of the currency.

amount

integer
必須
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 "{title}":

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

Path parameters for "{title}"

projectId

string
必須
ID of the project.

playerId

string
必須
ID of the player.

currencyId

string
必須
Resource ID of the currency.

Header parameters for "{title}"

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 "{title}"

configAssignmentHash

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

Request body for "{title}"

Media Type:
application/json

currencyId

string
deprecated
Resource ID of the currency.

amount

integer
必須
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 "{title}":

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

Path parameters for "{title}"

projectId

string
必須
ID of the project.

playerId

string
必須
ID of the player.

Header parameters for "{title}"

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 "{title}"

configAssignmentHash

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

Request body for "{title}"

Media Type:
application/json

inventoryItemId

string
必須
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 "{title}":

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
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 "{title}"

projectId

string
必須
ID of the project.

playerId

string
必須
ID of the player.

Header parameters for "{title}"

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 "{title}"

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 "{title}":

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

Path parameters for "{title}"

projectId

string
必須
ID of the project.

playerId

string
必須
ID of the player.

playersInventoryItemId

string
必須
The
playersInventoryItemId
of the item to be updated.

Header parameters for "{title}"

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 "{title}"

configAssignmentHash

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

Request body for "{title}"

Media Type:
application/json

instanceData

object
必須
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 "{title}":

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

Path parameters for "{title}"

projectId

string
必須
ID of the project.

playerId

string
必須
ID of the player.

playersInventoryItemId

string
必須
The
playersInventoryItemId
of the item to be updated.

Header parameters for "{title}"

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 "{title}"

configAssignmentHash

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

writeLock

string
The writelock for a database entry.

Request body for "{title}"

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 "{title}":

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

Path parameters for "{title}"

projectId

string
必須
ID of the project.

playerId

string
必須
ID of the player.

Header parameters for "{title}"

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 "{title}"

configAssignmentHash

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

Request body for "{title}"

Media Type:
application/json

id

string
必須
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 "{title}":

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

Path parameters for "{title}"

projectId

string
必須
ID of the project.

playerId

string
必須
ID of the player.

Header parameters for "{title}"

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 "{title}"

configAssignmentHash

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

Request body for "{title}"

Media Type:
application/json

id

string
必須
ID of the purchase.

receipt

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

localCost

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

localCurrency

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

HTTP response status codes for "{title}":

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

Path parameters for "{title}"

projectId

string
必須
ID of the project.

playerId

string
必須
ID of the player.

Header parameters for "{title}"

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 "{title}"

configAssignmentHash

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

Request body for "{title}"

Media Type:
application/json

id

string
必須
ID of the purchase.

purchaseData

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

purchaseDataSignature

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

localCost

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

localCurrency

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

HTTP response status codes for "{title}":

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

Path parameters for "{title}"

projectId

string
必須
ID of the project.

playerId

string
必須
ID of the player.

Header parameters for "{title}"

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 "{title}"

configAssignmentHash

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

HTTP response status codes for "{title}":

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": {} } ]}

Copyright © 2026 Unity Technologies
法規事項プライバシーポリシークッキーDocumentation Terms of Use私の個人情報を販売または共有しないプライバシーに関する選択 (クッキー設定)

"Unity" の名称、Unity のロゴ、およびその他の Unity の商標は、米国およびその他の国における Unity Technologies またはその関係会社の商標または登録商標です (詳しくはこちら)。その他の名称またはブランドは該当する所有者の商標です。

一部のページは利便性向上のため機械翻訳を使用しており、内容に不正確な表現が含まれる場合があります。内容に齟齬または不一致が生じた場合は、英語版を正本とします。