Purchasing/Product APIs

Players can buy products (game passes + consumables) for Sparks in your game. When a purchase happens, All Out calls your purchase handler so you can grant the item or feature.

For creating products and viewing analytics, see In Game Products.

Product types (quick overview)

• Game passes: one-time, persistent unlocks (admin pass, permanent ability, house ownership)
• Consumables: can be bought multiple times (potion, temporary buff, one-time coin pack)

Product types are configured in the creator portal. See In Game Products.

Purchasing API reference

Product :: struct {
    id: string;
    name: string;
    description: string;
    price: s64;
    consumable: bool;
    icon: Texture_Asset;
}

Purchasing :: struct {
    prompt_purchase :: proc(player: Player, id: string);
    owns_product    :: proc(player: Player, id: string) -> bool;
    get_product     :: proc(id: string) -> Product;
}

Prompting a purchase

To start the purchase flow, call Purchasing.prompt_purchase with a product ID.

BUY_DOUBLE_JUMP_ID :: "prod_double_jump";

try_prompt_double_jump :: proc(player: Player) {
    Purchasing.prompt_purchase(player, BUY_DOUBLE_JUMP_ID);
}

The product ID is shown in the monetization/products page in the creator portal (you can click to copy it). See In Game Products.

Checking if a player owns a product (game passes)

For game passes, you can gate gameplay features by checking ownership.

ADMIN_PASS_ID :: "prod_admin";

is_admin :: proc(player: Player) -> bool {
    return Purchasing.owns_product(player, ADMIN_PASS_ID);
}

Consumables can be bought multiple times, owns_product shouldn't be used to award them. Consumables are usually granted in your purchase handler (coins, items, buffs, etc).

Reading product info (name/price/icon)

If you want to show a “Buy” UI or log product info, fetch the product definition by ID:

product := Purchasing.get_product("prod_double_jump");
log_info("Product % costs % sparks", {product.name, product.price});

The purchase handler (granting)

When a player buys a product in your game, All Out calls:

ao_purchase_handler :: proc(player: Player, id: string) -> bool

If your game does not define ao_purchase_handler, non-consumable products are granted automatically so they work with Purchasing.owns_product. Consumable products still require a handler and are marked as grant failures without one.

You should:

• Switch on the product ID
• Grant the item/feature
• Return true if the grant succeeded
• Return false if the grant failed (inventory full, missing prerequisite, etc)

COIN_PACK_ID :: "prod_coin_pack_small";
DOUBLE_JUMP_ID :: "prod_double_jump";

ao_purchase_handler :: proc(player: Player, id: string) -> bool {
    switch id {
        case COIN_PACK_ID: {
            // Example: grant coins (consumable)
            Economy.deposit_currency(player, "Coins", 500);
            Notifier.notify(player, "Thanks! +500 coins");
            return true;
        }
        case DOUBLE_JUMP_ID: {
            // Example: game pass unlock (persistent)
            // You typically just enable it via owns_product() checks elsewhere.
            // Still return true so the purchase is considered granted.
            Notifier.notify(player, "Double Jump unlocked!");
            return true;
        }
    }

    // Unknown ID
    return false;
}

Grant failures & retries

If your purchase handler returns false, the purchase is marked as a grant failure.

• Grant failures are shown in the creator portal
• They're automatically retried when the player joins until they succeed
• You can manually re-run a purchase handler by marking a purchase as “ungranted” in the player data UI

See:

• In Game Products (“Purchase Handlers / Grant Failures”)
• Editing/Viewing Player Data (“Purchases” section)

Cross-game (hub + minigames)

If you use game parenting, purchases can be shared across your games. See Cross-Game Products/Data.