Purchases API

Let players spend RunBucks 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 RunBucks?

RunBucks are the platform's hard currency. Players acquire RunBucks 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 RunBucks purchases—transactions where users spend RunBucks inside your game.

Quick Start

import RundotGameAPI from '@series-inc/rundot-game-sdk/api'

// Check player's RunBucks balance
const balance = await RundotGameAPI.iap.getHardCurrencyBalance()
console.log(`Player has ${balance} RunBucks`)

// Spend RunBucks on an item
const purchase = await RundotGameAPI.iap.spendCurrency('bundle_sword', 1)
if (purchase.success) {
  unlockItem('bundle_sword')
}

Storefront Helpers

// Launch the native RunBucks store
await RundotGameAPI.iap.openStore()

// Fetch currency icon for your UI
const icon = await RundotGameAPI.iap.getCurrencyIcon()
document.querySelector('#currency-icon').src = icon

Complete Purchase Flow

async function purchaseItem(itemId: string, cost: number) {
  // 1. Check balance first
  const balance = await RundotGameAPI.iap.getHardCurrencyBalance()
  
  if (balance < cost) {
    // Not enough RunBucks - prompt to buy more
    await RundotGameAPI.iap.openStore()
    return { success: false, reason: 'insufficient_funds' }
  }
  
  // 2. Attempt purchase
  try {
    const result = await RundotGameAPI.iap.spendCurrency(itemId, cost)
    
    if (result.success) {
      // 3. Track the purchase
      await RundotGameAPI.analytics.recordCustomEvent('purchase_complete', {
        itemId,
        cost,
        newBalance: result.newBalance,
      })
      
      return { success: true, newBalance: result.newBalance }
    }
    
    return { success: false, reason: 'purchase_failed' }
  } catch (error) {
    return { success: false, reason: 'error', error }
  }
}

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

import { useEffect, useState } from 'react';
import { RunSubscriptionsResponse } from '@series-inc/rundot-game-sdk/api';

function Paywall() {
  const [subscriptions, setSubscriptions] = useState<RunSubscriptionsResponse>({});

  // Fetch all subscriptions across all tiers, or pass a tier to filter
  useEffect(() => {
    RundotGameAPI.iap
      .getSubscriptions() // optionally pass a tier: getSubscriptions('CORE') if you want just CORE subscriptions
      .then(setSubscriptions);
  }, []);

  // Trigger the checkout flow for a given tier + interval
  const handlePurchase = async (tier: SubscriptionTier, interval: SubscriptionInterval) => {
    const result = await RundotGameAPI.iap.purchaseSubscription(tier, interval);
    if (result.success) {
      alert('Thanks for subscribing!');
    } else {
      // handle error
    }
  };

  return (
    <div>
      {Object.entries(subscriptions).map(([tier, packages]) => (
        <div key={tier}>
          <h2>{tier}</h2>
          {packages.map((sub) => (
            <button
              key={sub.interval}
              onClick={() => handlePurchase(tier as SubscriptionTier, sub.interval)}
            >
              <strong>{sub.description}</strong>
              <span>
                {sub.currencyCode} {sub.price} / {sub.interval}
              </span>
            </button>
          ))}
        </div>
      ))}
    </div>
  );
}

export default Paywall;

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) Core, Plus, Prime, Ultimate

// Returns true if the user has CORE, PLUS, PRIME, or ULTIMATE
const hasCoreAccess = await RundotGameAPI.iap.isUserSubscribed('CORE');

// Returns true only if the user has ULTIMATE
const hasUltimateAccess = await RundotGameAPI.iap.isUserSubscribed('ULTIMATE');

// Example: gate a feature behind PLUS or higher
if (await RundotGameAPI.iap.isUserSubscribed('PLUS')) {
  unlockPlusFeatures();
} else {
  showUpgradePrompt();
}

API Reference

Method	Returns	Description
getHardCurrencyBalance()	Promise<number>	Get player's current RunBucks balance
spendCurrency(itemId, amount)	Promise<{ success, newBalance }>	Spend RunBucks on an item
openStore()	Promise<void>	Open the native RunBucks store
getCurrencyIcon()	Promise<string>	Get the RunBucks icon URL for UI
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
hasUserMadePurchase()	Promise<boolean>	Check if the user has ever made a purchase on RUN

---

Subscription Offerings

Tier: CORE

Interval	Price
WEEKLY	$1.99
MONTHLY	$7.99
ANNUAL	$79.99

// Returns true if the user has CORE or higher
const hasCoreAccess = await RundotGameAPI.iap.isUserSubscribed('CORE');

RundotGameAPI.iap.getSubscriptions() // optionally pass a tier: getSubscriptions('CORE') if you want just CORE subscriptions

const result = await RundotGameAPI.iap.purchaseSubscription('CORE', 'weekly');
// or
const result = await RundotGameAPI.iap.purchaseSubscription('CORE', 'monthly');
// or
const result = await RundotGameAPI.iap.purchaseSubscription('CORE', 'annual');

---

Tier: PLUS

Interval	Price
WEEKLY	$2.99
MONTHLY	$11.99
ANNUAL	$119.99

// Returns true if the user has PLUS or higher
const hasPlusAccess = await RundotGameAPI.iap.isUserSubscribed('PLUS');

RundotGameAPI.iap.getSubscriptions() // optionally pass a tier: getSubscriptions('PLUS') if you want just PLUS subscriptions

const result = await RundotGameAPI.iap.purchaseSubscription('PLUS', 'weekly');
// or
const result = await RundotGameAPI.iap.purchaseSubscription('PLUS', 'monthly');
// or
const result = await RundotGameAPI.iap.purchaseSubscription('PLUS', 'annual');

---

Tier: PRIME

Interval	Price
WEEKLY	$9.99
MONTHLY	$34.99
ANNUAL	$299.99

// Returns true if the user has PRIME or higher
const hasPrimeAccess = await RundotGameAPI.iap.isUserSubscribed('PRIME');

RundotGameAPI.iap.getSubscriptions() // optionally pass a tier: getSubscriptions('PRIME') if you want just PRIME subscriptions

const result = await RundotGameAPI.iap.purchaseSubscription('PRIME', 'weekly');
// or
const result = await RundotGameAPI.iap.purchaseSubscription('PRIME', 'monthly');
// or
const result = await RundotGameAPI.iap.purchaseSubscription('PRIME', 'annual');

---

Tier: ULTIMATE

Interval	Price
WEEKLY	$14.99
MONTHLY	$39.99
ANNUAL	$349.99

// Returns true if the user has ULTIMATE or higher
const hasUltimateAccess = await RundotGameAPI.iap.isUserSubscribed('ULTIMATE');

RundotGameAPI.iap.getSubscriptions() // optionally pass a tier: getSubscriptions('ULTIMATE') if you want just ULTIMATE subscriptions

const result = await RundotGameAPI.iap.purchaseSubscription('ULTIMATE', 'weekly');
// or
const result = await RundotGameAPI.iap.purchaseSubscription('ULTIMATE', 'monthly');
// or
const result = await RundotGameAPI.iap.purchaseSubscription('ULTIMATE', 'annual');

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.

• Persist receipts or transaction IDs from the result payload if you need audit trails on your backend.

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

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