ドキュメント

IAP Client API

IAP Client API

IAP API

Introduction

Unity IAP is a unified solution for managing digital commerce and implementing in-app purchases across games, stores, and third-party payment providers. These APIs provide a fully managed entitlement system that handles orders and fulfillment through third-party payment providers.

Concepts

Payment Providers

  • Order: A purchase initiated through a third-party payment provider, managed through the entitlement system from creation to fulfillment.
  • Entitlement: A player's right to access a purchased product, tracked and managed across all supported payment providers.
Download OpenAPI specification:

Create an order

Initiates an order for a player to purchase a specific product from a payment provider. Supports webview-based flows and will support other flows in the future (which could return additional order data). The player information is stored and used to personalize the order experience. Currently supports exactly one SKU in the request.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "{title}"

projectId

string
必須
ID of the Unity project.

environmentId

string
必須
ID of the Unity environment.

Request body for "{title}"

Media Type:
application/json

player

object
必須
Player information for creating an order

playerId

string
Unity Player ID (automatically set from authentication token, should not be provided in request)

displayName

string
Player's display name

locale

string
必須
example: en-US
Player's locale in BCP 47 format

identity

object
必須
example: {"unity.installation_id":"abc123","session.id":"xyz789"}
Player identity information. The identity object is required but can be empty.

unity.impression_id

string
Impression ID

unity.installation_id

string
Unity installation ID

unity.fid

string
Unity FID

unity.gaid

string
Google Advertising ID

unity.gappid

string
Google App ID (same value as the Firebase app ID). Declared in the contract but not currently populated by the SDK, so this is always empty in practice; use unity.firebase_app_id for the Firebase app ID.

unity.idfa

string
iOS Identifier for Advertisers

unity.idfv

string
iOS Identifier for Vendors

unity.mega_session_id

string
Unity mega session ID

session.id

string
Session ID

unity.consent_state.ads_intent

string
User consent for ads

unity.consent_state.analytics_intent

string
User consent for analytics

unity.analytics_id

string
UA2 Analytics ID

unity.app_instance_id

string
Firebase ID

unity.firebase_session_id

string
Firebase session ID

unity.firebase_app_id

string
Firebase app ID (from google-services.json, set in the Firebase console)

unity.iap_sdk_version

string
IAP SDK version

unity.engine_version

string
Unity Engine version

unity.application_version

string
Developer-set application/build version of the game (e.g. semver)

unity.user_id

string
Unity user identifier provided by the Game Developer

unity.installation_timestamp

string
RFC 3339 timestamp of when the game was installed on the player's device

[additionalProperties]

string
No description

skus

array[string]
deprecated
example: ["product-sku-123"]
Array of product SKUs. Currently must contain exactly one SKU. Deprecated in favour of 
catalogListingIds
; still supported during the transition period. Provide either 
skus
or 
catalogListingIds
.

catalogListingIds

array[string]
example: ["endgame/gems-100.ucat"]
Array of catalog listing identifiers to purchase. Currently must contain exactly one identifier. Replaces 
skus
because SKUs are not guaranteed to be unique. Each identifier is the Live Content config path of the catalog listing and typically looks like a relative file path. Provide either 
skus
or 
catalogListingIds
.

currency

string
必須
example: USD
Currency code in ISO 4217 format. Required. If the requested currency is not configured for the product, the order falls back to USD pricing. If neither the requested currency nor USD is configured, the order is rejected.

country

string
example: US
Country of purchase in ISO 3166-1 alpha-2 format. Used by payment providers that require a country-of-purchase signal (currently Codapay only); ignored by others. When omitted, the country is derived from the player's locale as a temporary backward-compatibility fallback for older SDK versions.

paymentProvider

string
example: stripe
Optional. Specify payment provider instead of using the default one configured for this project environment.

uiMode

string
example: embedded
Optional. One of 
hosted
or 
embedded
. How the checkout is presented. 
hosted
(default) returns a provider-hosted checkout page in 
url
. 
embedded
returns an 
embeddedInfo
object (client secret, plus a publishable key for Stripe) for rendering an in-page form via the payment provider's JS SDK and leaves 
url
empty. Only 
stripe
supports 
embedded
; other providers reject the request. In 
embedded
mode the player is never redirected, so only payment methods that don't require a redirect are offered (cards, Apple Pay, Google Pay, Link).

entryChannel

string
example: game_deeplink
Optional. The player-journey channel the order started from, independent of the referer-derived purchase origin. One of 
game_deeplink
or 
direct
: 
game_deeplink
means the session began at the in-game Purchase UI (i.e. a deep-linked webshop session); 
direct
means an organic browser first webshop visit. Client-asserted and analytics-grade (same trust level as the 
player.identity
map). Honored only for orders arriving with a webshop referer; ignored for in-app/SDK orders (which are always treated as 
game_deeplink
) and silently dropped when unrecognized. When omitted, the channel is left unspecified.

externalTransactionTokens

array[object]
Optional external-link transaction tokens, used by developers to self-report the transaction to Apple/Google. Stored with the order and surfaced in order webhooks; not returned in the order response. Up to two tokens may be supplied because a single Apple external purchase can yield two distinct token types depending on the region — for example an 
acquisition
token and a 
linkOut
token.

store

string
必須
The app store the token targets, determining where the transaction is reported.

token

string
必須
The external purchase/transaction token, stored and forwarded opaquely.

type

string
Apple-only token category. Only valid when store is "apple"; omit for Google.

redirectUrls

object
Optional. Per-order override of the project's globally configured redirect URLs. When provided, 
successUrl
is required and the object fully replaces the global config for this order; when omitted, the global config is used.

successUrl

string
必須
example: https://shop.unity.com/studio/game?status=success
Redirect target after a successful checkout. Must be an absolute https URL on the project's webshop host (e.g. 
shop.unity.com
); other hosts are rejected.

cancelUrl

string
example: https://shop.unity.com/studio/game?status=cancelled
Redirect target when the player cancels or abandons checkout. Applies to providers with a cancel step (Stripe and mock checkout); ignored by providers without one. Must be on the project's webshop host.

customReferenceId

string
Optional. A unique custom identifier that you can set to any value to help reconcile IAP Orders with your internal system. Stored with the order and returned in the order response and order webhooks.

linkOutSessionId

string
Optional, internal. The opaque, backend-minted key from a prior link-out session registration (see registerLinkOutSession). Relayed verbatim by the webshop on a game-deeplinked order; the backend exchanges it for the registered device context. Ignored when absent, unrecognised, or when the session's owner does not match the ordering player.

metadata

object
Optional. Arbitrary key/value metadata stored with the order and returned in the order response and order webhooks. Limited to 20 keys; each key is limited to 40 bytes and each value to 100 bytes. Limits are enforced on the UTF-8 byte length, not the character count, so multi-byte characters count multiple times. Orders exceeding these limits are rejected.

deviceInfo

object
Device information provided by the IAP SDK for analytics enrichment.

language

string
example: en-US
System language of the device (BCP 47 format).

platform

string
example: ios
Platform the game is running on (e.g. 
ios
, 
android
).

localeList

array[string]
example: ["en-US","es-US"]
Ordered list of locales configured on the device.

deviceModel

string
example: iPhone13,3
Device model identifier.

systemBootTime

integer
example: 1778138688
Unix timestamp (seconds) of the last system boot.

osVersion

string
example: 17.0
Operating system version.

appBundleId

string
example: com.example.game
Application bundle identifier.

totalSpace

integer
example: 256000000000
Total device storage in bytes.

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "player": { "playerId": "string", "displayName": "string", "locale": "en-US", "identity": { "unity.installation_id": "abc123", "session.id": "xyz789" } }, "skus": [ "product-sku-123" ], "catalogListingIds": [ "endgame/gems-100.ucat" ], "currency": "USD", "country": "US", "paymentProvider": "stripe", "uiMode": "embedded", "entryChannel": "game_deeplink", "externalTransactionTokens": [ { "store": "apple", "token": "string", "type": "acquisition" } ], "redirectUrls": { "successUrl": "https://shop.unity.com/studio/game?status=success", "cancelUrl": "https://shop.unity.com/studio/game?status=cancelled" }, "customReferenceId": "string", "linkOutSessionId": "string", "metadata": {}, "deviceInfo": { "language": "en-US", "platform": "ios", "localeList": [ "en-US", "es-US" ], "deviceModel": "iPhone13,3", "systemBootTime": 1778138688, "osVersion": "17.0", "appBundleId": "com.example.game", "totalSpace": 256000000000 }}' \ "https://iap.services.api.unity.com/v1/projects/{projectId}/environments/{environmentId}/order"

Response example

{ "id": "string", "projectId": "string", "environmentId": "string", "playerId": "string", "paymentProvider": "stripe", "paymentProviderResourceId": "string", "url": "https://example-webshop.com/products/sku123?session=...", "uiMode": "hosted", "embeddedInfo": { "clientSecret": "cs_test_..._secret", "publishableKey": "pk_test_..." }, "lineItems": [ { "sku": "product-123", "catalogListingId": "endgame/gems-100.ucat", "productType": "consumable" } ], "status": "string", "fulfilledAt": "2020-04-01T13:07:23Z", "revokedAt": "2020-04-01T13:07:23Z", "customReferenceId": "string", "metadata": {}, "createdAt": "2020-04-01T13:07:23Z", "updatedAt": "2020-04-01T13:07:23Z"}

Register link-out device context

Registers the in-game IAP SDK's device-context bundle (device identifiers and device info) before a webshop link-out and returns a backend-minted linkOutSessionId. These identifiers are PII and must not travel on the link URL: the webshop carries only the opaque key and order-create resolves it server-side. The bundle is bound to the authenticated player and retained with a short TTL.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "{title}"

projectId

string
必須
ID of the Unity project.

environmentId

string
必須
ID of the Unity environment.

Request body for "{title}"

Media Type:
application/json

identity

object
必須
example: {"unity.installation_id":"abc123","session.id":"xyz789"}
Player identity information. The identity object is required but can be empty.

unity.impression_id

string
Impression ID

unity.installation_id

string
Unity installation ID

unity.fid

string
Unity FID

unity.gaid

string
Google Advertising ID

unity.gappid

string
Google App ID (same value as the Firebase app ID). Declared in the contract but not currently populated by the SDK, so this is always empty in practice; use unity.firebase_app_id for the Firebase app ID.

unity.idfa

string
iOS Identifier for Advertisers

unity.idfv

string
iOS Identifier for Vendors

unity.mega_session_id

string
Unity mega session ID

session.id

string
Session ID

unity.consent_state.ads_intent

string
User consent for ads

unity.consent_state.analytics_intent

string
User consent for analytics

unity.analytics_id

string
UA2 Analytics ID

unity.app_instance_id

string
Firebase ID

unity.firebase_session_id

string
Firebase session ID

unity.firebase_app_id

string
Firebase app ID (from google-services.json, set in the Firebase console)

unity.iap_sdk_version

string
IAP SDK version

unity.engine_version

string
Unity Engine version

unity.application_version

string
Developer-set application/build version of the game (e.g. semver)

unity.user_id

string
Unity user identifier provided by the Game Developer

unity.installation_timestamp

string
RFC 3339 timestamp of when the game was installed on the player's device

[additionalProperties]

string
No description

deviceInfo

object
Device information provided by the IAP SDK for analytics enrichment.

language

string
example: en-US
System language of the device (BCP 47 format).

platform

string
example: ios
Platform the game is running on (e.g. 
ios
, 
android
).

localeList

array[string]
example: ["en-US","es-US"]
Ordered list of locales configured on the device.

deviceModel

string
example: iPhone13,3
Device model identifier.

systemBootTime

integer
example: 1778138688
Unix timestamp (seconds) of the last system boot.

osVersion

string
example: 17.0
Operating system version.

appBundleId

string
example: com.example.game
Application bundle identifier.

totalSpace

integer
example: 256000000000
Total device storage in bytes.

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "identity": { "unity.installation_id": "abc123", "session.id": "xyz789" }, "deviceInfo": { "language": "en-US", "platform": "ios", "localeList": [ "en-US", "es-US" ], "deviceModel": "iPhone13,3", "systemBootTime": 1778138688, "osVersion": "17.0", "appBundleId": "com.example.game", "totalSpace": 256000000000 }}' \ "https://iap.services.api.unity.com/v1/projects/{projectId}/environments/{environmentId}/link-out-session"

Response example

{ "linkOutSessionId": "7f3d8c2a-1b4e-4c6a-9d2f-7a1b2c3d4e5f"}

List eligible configured payment providers

Returns the list of configured payment providers the calling player is eligible for, based on their Live Releases variant tags and the project's tag-to-provider routing configuration. Providers are listed in priority order, highest first; clients should use the first entry by default. An empty list means no provider is eligible for this player; clients should handle this as a normal "external payment unavailable" state.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "{title}"

projectId

string
必須
ID of the Unity project.

environmentId

string
必須
ID of the Unity environment.

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://iap.services.api.unity.com/v1/projects/{projectId}/environments/{environmentId}/payment-providers"

Response example

{ "providers": [ "stripe" ], "paymentOptionsPopupEnabled": true}

List player entitlements

Returns an array of all orders that the player is entitled to.
Important: Revoked orders are never included in the response, regardless of product type.
Entitlement logic by product type:
  • Consumables: Included if not yet fulfilled.
  • Non-consumables: Always included.
  • Subscriptions: Not yet supported for external payment providers. Future behavior will be similar to non-consumables but will also require the subscription to not be expired.
If there is a mix of types in the order, the order will be returned if any of the types are entitled.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "{title}"

projectId

string
必須
ID of the Unity project.

environmentId

string
必須
ID of the Unity environment.

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://iap.services.api.unity.com/v1/projects/{projectId}/environments/{environmentId}/orders/entitled"

Response example

[ { "id": "string", "projectId": "string", "environmentId": "string", "playerId": "string", "paymentProvider": "stripe", "paymentProviderResourceId": "string", "url": "https://example-webshop.com/products/sku123?session=...", "uiMode": "hosted", "embeddedInfo": { "clientSecret": "cs_test_..._secret", "publishableKey": "pk_test_..." }, "lineItems": [ { "sku": "product-123", "catalogListingId": "endgame/gems-100.ucat", "productType": "consumable" } ], "status": "string", "fulfilledAt": "2020-04-01T13:07:23Z", "revokedAt": "2020-04-01T13:07:23Z", "customReferenceId": "string", "metadata": {}, "createdAt": "2020-04-01T13:07:23Z", "updatedAt": "2020-04-01T13:07:23Z" }]

Get order status

Retrieves the status of an order. Returns 404 if no information has been received from the payment provider about the purchase yet.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "{title}"

projectId

string
必須
ID of the Unity project.

environmentId

string
必須
ID of the Unity environment.

orderId

string
必須
ID of the Unity order.

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://iap.services.api.unity.com/v1/projects/{projectId}/environments/{environmentId}/orders/{orderId}"

Response example

{ "id": "string", "projectId": "string", "environmentId": "string", "playerId": "string", "paymentProvider": "stripe", "paymentProviderResourceId": "string", "url": "https://example-webshop.com/products/sku123?session=...", "uiMode": "hosted", "embeddedInfo": { "clientSecret": "cs_test_..._secret", "publishableKey": "pk_test_..." }, "lineItems": [ { "sku": "product-123", "catalogListingId": "endgame/gems-100.ucat", "productType": "consumable" } ], "status": "string", "fulfilledAt": "2020-04-01T13:07:23Z", "revokedAt": "2020-04-01T13:07:23Z", "customReferenceId": "string", "metadata": {}, "createdAt": "2020-04-01T13:07:23Z", "updatedAt": "2020-04-01T13:07:23Z"}

Update an order

Updates an order. Used to mark an order as fulfilled, cancelled, or revoked.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "{title}"

projectId

string
必須
ID of the Unity project.

environmentId

string
必須
ID of the Unity environment.

orderId

string
必須
ID of the Unity order.

Request body for "{title}"

Media Type:
application/json

status

string
必須
example: fulfilled
Updates the order status. Supported values are 
fulfilled
, 
cancelled
, and 
revoked
. Only orders with 
created
status can be marked as 
cancelled
. Only orders with 
paid
status can be marked as 
fulfilled
. Orders with 
paid
or 
fulfilled
status can be marked as 
revoked
. Once cancelled or revoked, an order cannot be changed to another status.

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X PATCH \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "status": "fulfilled"}' \ "https://iap.services.api.unity.com/v1/projects/{projectId}/environments/{environmentId}/orders/{orderId}"

Response example

{ "id": "string", "projectId": "string", "environmentId": "string", "playerId": "string", "paymentProvider": "stripe", "paymentProviderResourceId": "string", "url": "https://example-webshop.com/products/sku123?session=...", "uiMode": "hosted", "embeddedInfo": { "clientSecret": "cs_test_..._secret", "publishableKey": "pk_test_..." }, "lineItems": [ { "sku": "product-123", "catalogListingId": "endgame/gems-100.ucat", "productType": "consumable" } ], "status": "string", "fulfilledAt": "2020-04-01T13:07:23Z", "revokedAt": "2020-04-01T13:07:23Z", "customReferenceId": "string", "metadata": {}, "createdAt": "2020-04-01T13:07:23Z", "updatedAt": "2020-04-01T13:07:23Z"}

Resolve store-specific product ids to their Unity SKUs

Reverse-lookup endpoint that resolves store-specific product ids (Apple/Google/etc.) back to their Unity SKU and product type for the caller's live release. Returned as a map keyed by store, then by store-specific id; unmatched ids are omitted. When no storeOverrideId is supplied, every store-specific id for the requested store is returned.
A single store-specific id is expected to map to exactly one Unity SKU across the catalog. If multiple Unity SKUs (or multiple variants of the same Unity SKU with different types) declare the same store-specific id on the same store, only the first match is returned; later collisions are skipped and logged server-side. Keep store-specific ids unique across your catalog to avoid this.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "{title}"

projectId

string
必須
ID of the Unity project.

Query parameters for "{title}"

storeOverrideId

array
example: com.example.coins.100,gems_30_google
Store-specific product id to resolve. Optional, may be supplied multiple times. When omitted, all store-specific ids for the given store are returned.

store

string
必須
example: apple
Case-insensitive store filter (e.g., 'apple', 'google', 'xbox', 'applemacos'). Only that store key appears in the response.

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://iap.services.api.unity.com/v1/projects/{projectId}/catalog/store-overrides"

Response example

{ "google": { "30_GEMS_GOOGLE": { "uSku": "gems_30", "type": "Consumable" } }, "apple": { "30_GEMS_APPLE": { "uSku": "gems_30", "type": "Consumable" } }, "xbox": { "30_GEMS_XBOX": { "uSku": "gems_30", "type": "Consumable" } }, "applemacos": { "30_GEMS_MACOS": { "uSku": "gems_30", "type": "Consumable" } }}