Purchases API
Let players spend RUN Bits to buy digital goods and entitlements in your game. The SDK handles platform billing flows: your game just requests balances and initiates transactions.
What Are RUN Bits?
RUN Bits are the platform's hard currency. Players acquire RUN Bits through the platform store, then spend them inside games for digital goods, power-ups, cosmetics, or other entitlements.
Note: "In-App Purchases" refers to FIAT transactions on the platform or in-game. This API specifically handles RUN Bits purchases: transactions where users spend RUN Bits inside your game.
Quick Start
import RundotGameAPI from '@series-inc/rundot-game-sdk/api'
// Check player's RUN Bits balance
const balance = await RundotGameAPI.iap.getHardCurrencyBalance()
console.log(`Player has ${balance} RUN Bits`)
// Spend RUN Bits on an item
const purchase = await RundotGameAPI.iap.spendCurrency('bundle_sword', 1)
if (purchase.success) {
unlockItem('bundle_sword')
}Storefront Helpers
Complete Purchase Flow
You can use hasUserMadePurchase to check if the user has ever made a purchase on RUN. You could use this information to adjust prices in your store, or show certain bundles only to non-spenders
Subscription Paywall with Checkout Flow
Checking Subscription Status
Use isUserSubscribed to gate content or features behind a subscription tier. This method respects tier hierarchy: if a user has a higher tier than the one being checked, it returns true. The tier hierarchy is (lowest to highest) Lite, Core, Plus, Prime, Ultimate
API Reference
getHardCurrencyBalance()
Promise<number>
Get player's current RUN Bits balance
spendCurrency(productId, amount, options?)
Promise<{ success: boolean; error?: string }>
Spend RUN Bits on an item. Accepts an optional options object (see below). On success: false, error carries the reason ('USER_CANCELLED' when the player declines).
openStore()
Promise<{ purchased: boolean; newBalance: number }>
Open the native RUN Bits store. Read purchased and the refreshed newBalance after it closes instead of refetching the balance.
getCurrencyIcon(options?)
Promise<{ base64Data: string }>
Get the currency icon as raw base64. Wrap it in a data URI ('data:image/png;base64,' + icon.base64Data) to use as an <img> src. Optionally pass { variant, size } to pick the treatment (gradient or the tintable mono) and artwork tier — see the full reference below.
isUserSubscribed(
tier)
Promise<boolean>
Check if the user has a certain subscription tier. Will also return true if the user has a higher subscription tier.
getSubscriptions(
tier?)
Promise<RunSubscriptionsResponse>
Get a list of subscriptions available by tier. Use these to show a paywall to the user. You can optionally pass a tier to this method to get subscriptions for that tier only.
purchaseSubscription(tier, interval)
Promise<PurchaseSubscriptionResponse>
Trigger a checkout flow for a given subscription (identified by its tier and interval). Rejects with a RundotApiError (UNSUPPORTED_SUBSCRIPTION_INTERVAL) if the tier does not offer that interval — LITE is weekly-only.
hasUserMadePurchase()
Promise<boolean>
Check if the user has ever made a purchase on RUN
listDirectPurchaseSkus()
Promise<DirectPurchaseSku[]>
List your game's active real-money items as a per-store pricing view derived from your tagged shop config. Always scoped to the running game — there is no way to read another game's items. Read-only — author these in shop.config.json and buy them with shop.purchase. See Direct Purchase Catalog.
spendCurrency(productId, amount, options?)
spendCurrency takes an optional third argument, SpendCurrencyOptions. Every field is optional. Both SpendCurrencyOptions and the SpendCurrencyResult it resolves to are named, importable types from the package root, @series-inc/rundot-game-sdk (not the /api subpath), so you can annotate your own helpers with them.
screenName
string
No
Screen/route name where the purchase occurred. Used for analytics only.
description
string
No
Short human-readable label of what is being bought (e.g. "Unlock level 5"). The host renders this in the spend-confirmation dialog so the player sees what they are paying for. Sanitized and truncated by the host before display.
beneficiaryId
string
No
Profile id of a UGC creator the spend should be attributed to for revenue share. Forwarded to the server for revshare bookkeeping.
contentEntryId
string
No
Story-level UGC entry id the spend buys (e.g. a RUN.tv episode unlock). When set, the server keys the recommendation purchase signal to that specific content item instead of the host game.
It resolves to a SpendCurrencyResult:
success
boolean
Whether the spend completed.
error
string (optional)
Present only on success: false. The one stable value is 'USER_CANCELLED' (the player declined the host dialog; no currency was deducted). Any other value is a server-side message and is not stable, so don't branch on it.
spendCurrency does not return a balance. If you need the post-spend balance, call getHardCurrencyBalance() afterward.
openStore(): Promise<OpenStoreResult>
Opens the native RUN Bits store and resolves once it closes. The result lets you react to a purchase without a separate balance fetch. OpenStoreResult is a named, importable type from the package root, @series-inc/rundot-game-sdk (not the /api subpath).
purchased
boolean
Whether a purchase was completed during the store session.
newBalance
number
The updated RUN Bits balance after the store closed (saves a refetch).
getCurrencyIcon(options?): Promise<{ base64Data: string }>
Returns the RUN Bits icon as base64. Use it in an image source as shown below.
Defaults to gradient at md size. When testing locally, variant and size options are ignored.
variant
'gradient' | 'mono'
'gradient'
Which treatment of the mark to serve.
size
'xs' | 'sm' | 'md' | 'detail'
'md'
Artwork tier — pick the one nearest your rendered size.
Choosing a variant. gradient is the filled brand chip and carries the most brand recognition. mono is a line mark drawn in pure white with the shape in the alpha channel, so it takes a tint cleanly — reach for it when the gradient fights your palette, and tint it rather than hand-recolouring the PNG. Which one serves your game is your call.
The two are different artwork, not one silhouette recoloured, so they don't share a bounding box — don't assume identical optical weight when swapping between them in a fixed-size slot.
Choosing a size. Each tier is drawn for its display range rather than downsampled from one master, and its canvas is 4x the top of that range, so you only ever downscale.
xs
≤16px
64²
sm
16–24px
96²
md
24–48px
192²
detail
≥48px
512²
detail in gradient is ~80KB before base64 encoding — request it only when you actually draw the mark large.
Older versions of the RUN app may ignore these options and return their default icon.
Direct Purchase Catalog
Direct purchases are real-money products (FIAT, billed through the platform store — App Store, Google Play, Steam, or web checkout), unlike spendCurrency, which spends RUN Bits. The platform handles billing, fulfillment, and refunds server-side.
Key Architecture: File-Only Configuration
No Store Console or Dashboard Setup: Developers do not configure products or SKUs on platforms like Google Play or the App Store. File configuration in your project is all that is necessary. RUN operates a universal platform price ladder where all store products are pre-provisioned and shared across all games.
How SKUs are Provisioned: SKUs are never created individually per game. Instead, your game pins an item in
rundot/shop.config.jsonto a platformtierId(e.g.,tier_099,tier_499). When you deploy or upload your server config (rundot game upload-server-config), the platform automatically resolves the store products, handles checkout, and fulfills entitlements server-side.Supported Storefronts (Web, iOS, Android, Steam): All platform price tiers are live across Web, iOS, and Android, plus Steam. Web checkout works out of the box with zero extra configuration.
Sandbox Testing in Playground: In local Playground and preview environments, direct purchases operate in sandbox mode, allowing you to test checkout, order completion, and entitlement grants end-to-end without real charges.
Standard Platform Price Ladder
The following rungs are pre-provisioned and available across Web, iOS, Android, and Steam:
tier_099
$0.99
Web, iOS, Android, Steam
tier_199
$1.99
Web, iOS, Android, Steam
tier_299
$2.99
Web, iOS, Android, Steam
tier_399
$3.99
Web, iOS, Android, Steam
tier_499
$4.99
Web, iOS, Android, Steam
tier_599
$5.99
Web, iOS, Android, Steam
tier_699
$6.99
Web, iOS, Android, Steam
tier_799
$7.99
Web, iOS, Android, Steam
tier_899
$8.99
Web, iOS, Android, Steam
tier_999
$9.99
Web, iOS, Android, Steam
tier_1099
$10.99
Web, iOS, Android, Steam
tier_1199
$11.99
Web, iOS, Android, Steam
tier_1299
$12.99
Web, iOS, Android, Steam
tier_1399
$13.99
Web, iOS, Android, Steam
tier_1499
$14.99
Web, iOS, Android, Steam
tier_1599
$15.99
Web, iOS, Android, Steam
tier_1699
$16.99
Web, iOS, Android, Steam
tier_1799
$17.99
Web, iOS, Android, Steam
tier_1899
$18.99
Web, iOS, Android, Steam
tier_1999
$19.99
Web, iOS, Android, Steam
tier_2099
$20.99
Web, iOS, Android, Steam
tier_2199
$21.99
Web, iOS, Android, Steam
tier_2299
$22.99
Web, iOS, Android, Steam
tier_2399
$23.99
Web, iOS, Android, Steam
tier_2499
$24.99
Web, iOS, Android, Steam
tier_2599
$25.99
Web, iOS, Android, Steam
tier_2699
$26.99
Web, iOS, Android, Steam
tier_2799
$27.99
Web, iOS, Android, Steam
tier_2899
$28.99
Web, iOS, Android, Steam
tier_2999
$29.99
Web, iOS, Android, Steam
tier_3499
$34.99
Web, iOS, Android, Steam
tier_3999
$39.99
Web, iOS, Android, Steam
tier_4499
$44.99
Web, iOS, Android, Steam
tier_4999
$49.99
Web, iOS, Android, Steam
tier_5499
$54.99
Web, iOS, Android, Steam
tier_5999
$59.99
Web, iOS, Android, Steam
tier_6499
$64.99
Web, iOS, Android, Steam
tier_6999
$69.99
Web, iOS, Android, Steam
tier_7499
$74.99
Web, iOS, Android, Steam
tier_7999
$79.99
Web, iOS, Android, Steam
tier_8499
$84.99
Web, iOS, Android, Steam
tier_8999
$89.99
Web, iOS, Android, Steam
tier_9499
$94.99
Web, iOS, Android, Steam
tier_9999
$99.99
Web, iOS, Android, Steam
Use listDirectPurchaseSkus when you want raw per-store pricing. For rendering a storefront, prefer RundotGameAPI.shop.getCatalog() — it is per item, it carries names, assets, and sale prices, and it respects your version tag.
DirectPurchaseSku
Exported from the package root, @series-inc/rundot-game-sdk (not the /api subpath), along with DirectPurchaseStorePrice, DirectPurchaseStorePlatform, and DirectPurchaseGrantKind.
sku
string
The platform price-tier id (for example tier_499) — the same value the shop order reports as directPurchase.sku. Store products are shared across games, so this is not unique per item.
itemId
string?
The shop item this row was derived from. Use it to tell apart two items pinned to the same tier.
grants
DirectPurchaseGrant[]?
Every entitlement the item grants. Prefer this over grant, which is only the first — a real-money item may grant several things, and rendering just the first understates what the player is paying for.
gameId
string
The game this row belongs to.
tierId
string
The price tier, same value as sku.
nominalUsd
number
Nominal USD price (for display; the store of record sets the actual charge).
storePrices
DirectPurchaseStorePrice[]
Per-store pricing entries (see below).
grant
{ entitlementId: string; quantity: number; kind: DirectPurchaseGrantKind }
What a completed purchase grants. kind is 'consumable' (spent on use, can be bought again) or 'durable' (permanent unlock).
DirectPurchaseStorePrice
One entry per store the SKU is sold on. platform is 'web' | 'ios' | 'android' | 'steam' | 'telegram'; the other fields are optional and platform-specific (e.g. appStoreProductId on iOS, playProductId on Android, stars on Telegram). Use the optional displayPrice when present for localized price display.
Subscription Types
These types are exported from the package root, @series-inc/rundot-game-sdk (not the /api subpath).
SubscriptionTier
The canonical tier union accepted by isUserSubscribed, getSubscriptions, and purchaseSubscription. Lowest to highest: 'LITE', 'CORE', 'PLUS', 'PRIME', 'ULTIMATE'.
SubscriptionInterval
The billing interval passed to purchaseSubscription and returned on each RunSubscription. The accepted values are lowercase string literals.
RunSubscription
One purchasable subscription package (a single tier + interval combination), as returned by getSubscriptions.
currencyCode
string
Currency code for the subscription price.
interval
SubscriptionInterval
The billing interval. 'weekly' charges the buyer weekly.
price
number
The price, in the units of currencyCode.
description
string
The product description.
RunSubscriptionsResponse
The shape getSubscriptions resolves to: a map keyed by tier name, where each value is an array of RunSubscription packages (one per interval).
PurchaseSubscriptionResponse
The shape purchaseSubscription resolves to. success is true on a completed checkout and false on cancel or error.
Subscription Offerings
Tier: LITE
LITE is the entry tier and is weekly-only — there is no monthly or annual plan. purchaseSubscription('LITE', 'monthly') / ('LITE', 'annual') reject with UNSUPPORTED_SUBSCRIPTION_INTERVAL.
WEEKLY
$0.99
Tier: CORE
WEEKLY
$1.99
MONTHLY
$7.99
ANNUAL
$79.99
Tier: PLUS
WEEKLY
$2.99
MONTHLY
$11.99
ANNUAL
$119.99
Tier: PRIME
WEEKLY
$9.99
MONTHLY
$34.99
ANNUAL
$299.99
Tier: ULTIMATE
WEEKLY
$14.99
MONTHLY
$39.99
ANNUAL
$349.99
Best Practices
Check balances before attempting to spend to avoid bouncing players with generic errors.
Handle rejections gracefully: users may cancel or payments can fail mid-flow.
The spend and purchase results expose no receipt or transaction ID. If you need an audit trail, capture the
productIdand cost yourself (for example viaRundotGameAPI.analytics); the result only returnssuccess/error.Combine with
RundotGameAPI.analyticsto attribute purchases by SKU.Always show the player's current balance in your shop UI.
Last updated