For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Method
Returns
Description

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.

Field
Type
Required
Description

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:

Field
Type
Description

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).

Field
Type
Description

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.

Option
Type
Default
Description

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.

Tier
Draw it at
Canvas

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.json to a platform tierId (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 ID
Nominal USD
Supported Storefronts

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.

The catalog is always scoped to your game. listDirectPurchaseSkus takes no argument — there is no way to list another game's items.

Earlier SDK versions accepted a gameId argument. It is now ignored, so existing code keeps working, but it no longer selects the game and will be removed in the next major version. Remove it when convenient.

sku on each row is the price-tier id, not a per-game id, because the underlying store products are shared across games. Two of your items pinned to the same tier therefore produce two rows with the same sku, distinguished by itemId. That is also why this view cannot replace shop.getCatalog() for merchandising.

DirectPurchaseSku

Exported from the package root, @series-inc/rundot-game-sdk (not the /api subpath), along with DirectPurchaseStorePrice, DirectPurchaseStorePlatform, and DirectPurchaseGrantKind.

Field
Type
Description

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.

Not every tier offers every interval. LITE is weekly-only — it has no monthly or annual plan. purchaseSubscription rejects with a RundotApiError (code UNSUPPORTED_SUBSCRIPTION_INTERVAL) before any checkout if you request an interval a tier doesn't offer, so drive your paywall off the packages returned by getSubscriptions rather than assuming all three intervals exist. The other tiers (CORE, PLUS, PRIME, ULTIMATE) offer all three.

RunSubscription

One purchasable subscription package (a single tier + interval combination), as returned by getSubscriptions.

Field
Type
Description

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.

Interval
Price

WEEKLY

$0.99


Tier: CORE

Interval
Price

WEEKLY

$1.99

MONTHLY

$7.99

ANNUAL

$79.99


Tier: PLUS

Interval
Price

WEEKLY

$2.99

MONTHLY

$11.99

ANNUAL

$119.99


Tier: PRIME

Interval
Price

WEEKLY

$9.99

MONTHLY

$34.99

ANNUAL

$299.99


Tier: ULTIMATE

Interval
Price

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 productId and cost yourself (for example via RundotGameAPI.analytics); the result only returns success/error.

  • Combine with RundotGameAPI.analytics to attribute purchases by SKU.

  • Always show the player's current balance in your shop UI.

Last updated