API Contract

Base URL

https://api.susaplay.com

api.susaplay.com serves these route prefixes: /catalog, /publicCatalog, /save, /engagement, /analytics, /webhooks, /ai, /partners, /widgets, and the SDK’s /economy routes. Other routes are served at https://europe-west1-susaplay-2e8e3.cloudfunctions.net/{function}.

Authentication

Player and developer calls send a bearer token: a Firebase ID token, or the SusaPlay game-session token the SDK uses.

Authorization: Bearer {token}

When App Check is enforced, player routes also need an X-Firebase-AppCheck header; the SusaPlay page supplies it. Developer endpoints — reading games, versions, Addressables and analytics, build uploads, preview links, Addressables upload, publish and rollback, and adding store items and achievements — also accept a developer API key, for pipelines and AI tools:

Authorization: ApiKey {developer_api_key}

A key holds some of six permissions: games:read, analytics:read, builds:write, addressables:write, addressables:publish and game-config:write. See API Keys. Partner endpoints use a partner key:

Authorization: PartnerKey {partner_key}

Response format

Success

{
  "success": true,
  "data": { }
}

Error

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Human-readable description"
  }
}

Timestamps are ISO 8601 strings, except expiresAt fields, which are Unix seconds.

Error codes

Code	HTTP	Meaning
`UNAUTHENTICATED`	401	Missing or invalid token
`UNAUTHORIZED`	403	Authenticated but not permitted
`NOT_FOUND`	404	Resource does not exist
`INVALID_ARGUMENT`	400	Missing or malformed request body
`FORBIDDEN`	403	The token is scoped to another game
`INSUFFICIENT_SCOPE`	403	The API key lacks the permission named in `error.requiredScope`
`APP_CHECK_FAILED`	401	Missing or invalid App Check token
`INSUFFICIENT_BALANCE`	409	Not enough currency to complete spend
`INSUFFICIENT_ITEMS`	409	Not enough of a consumable to use
`DUPLICATE_ITEM`	409	A durable item the player already owns
`ITEM_NOT_FOUND`	404	No store item with that ID
`TOPUP_PACK_NOT_FOUND`	404	No top-up pack with that ID
`ITEM_NOT_PURCHASABLE`	409	The item’s price is not on sale, so it cannot be bought with money right now
`SIGN_IN_REQUIRED`	403	Paying, spending coins and earning coins need a signed-in player
`DUPLICATE_PURCHASE`	409	This rewarded-ad completion was already credited
`ADS_DISABLED`	403	Ads are turned off for the game
`AD_REWARD_COOLDOWN`, `AD_REWARD_LIMIT_REACHED`	429	Rewarded-ad cooldown or daily maximum
`GAME_NOT_FOUND`	404	The gameId or game key does not match any game
`VERSION_CONFLICT`	409	Cloud save version mismatch
`DUPLICATE`	409	Build version id already exists
`FAILED_PRECONDITION`	400, 403, 409	The request does not fit the current state — for example, too many builds already waiting for review, or rolling back to the release that is already live
`CONFLICT`	409	The state changed since you planned the request. Plan it again
`INCOMPATIBLE_CATALOG`	409	The Addressables content would break the live build. `error.compatibility` holds the check’s result
`OPERATION_IN_PROGRESS`	409	Another Addressables publish or rollback is running for this game
`ALREADY_EXISTS`	409	The store item or achievement ID is already registered
`INVALID_STATE`	409	The request does not fit the item’s state — for example, paying with coins is not allowed for this item
`INVALID_IMAGE`	400	An uploaded image has the wrong format or shape
`RELEASE_INCOMPLETE`	409	An Addressables release can no longer be restored because files it needs are gone
`RATE_LIMITED`, `TOO_MANY_REQUESTS`	429	Too many requests. `RATE_LIMITED` carries a `Retry-After` header
`PARTNER_API_UNAVAILABLE`, `PAYLOAD_TOO_LARGE`	502	A partner’s API did not answer, or answered too much
`INTERNAL`	500	Unexpected server error

CORS

Allowed origins are configured per deployment. Custom origins, including partner integrations, must be approved by SusaPlay before they can call the API.

Getting Started

Integration

SDK

API

Base URL

Authentication

Response format

Success

Error

Error codes

CORS

​Base URL

​Authentication

​Response format

​Success

​Error

​Error codes

​CORS

Base URL

Authentication

Response format

Success

Error

Error codes

CORS