> For the complete documentation index, see [llms.txt](https://docs.allout.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.allout.game/core-engine-concepts/purchasing-product-apis.md).

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

{% hint style="info" %}
For creating products and viewing analytics, see [In Game Products](https://docs.allout.game/monetization/in-game-products.md).
{% endhint %}

### 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](https://docs.allout.game/monetization/in-game-products.md).

### Purchasing API reference

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

Purchasing :: struct {
    prompt_purchase :: proc(player: Player, id: string);
    prompt_gift_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.

```go
BUY_DOUBLE_JUMP_ID :: "prod_double_jump";

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

{% hint style="info" %}
The product ID is shown in the monetization/products page in the creator portal (you can click to copy it). See [In Game Products](https://docs.allout.game/monetization/in-game-products.md).
{% endhint %}

### Prompting a gift

Call `Purchasing.prompt_gift_purchase` from a player UI action to let the local player choose a friend, review the product and price, and confirm the gift.

```go
Purchasing.prompt_gift_purchase(player, "YOUR_PRODUCT_ID");
```

The product must belong to the current game. A product priced at **0 Sparks** is a free gift; otherwise the sender pays the product's current Spark price. Both consumables and game passes use the existing product gifting system. The sender can search their friends, change the recipient, or cancel without sending anything. Call once per UI action. Only one purchase or gift prompt can be open at a time, and calls for another player do nothing.

All Out delivers the purchase to the **recipient**. Your existing `ao_purchase_handler` receives that recipient as `player`; do not grant the sender an item when opening the prompt. Gifts to offline friends remain pending until they join the game. Non-consumable ownership is checked for the recipient, so a sender can gift a pass they already own, but cannot buy a duplicate for a friend who owns it.

Editor playtests preview the gift confirmation without spending Sparks, sending an item, or invoking a purchase handler. Test delivery with a published game and test accounts.

For C# games, call `Purchasing.PromptGiftPurchase(productId)` on the client. Delivery uses the existing `Purchasing.PurchaseHandler` for the recipient.

### Checking if a player owns a product (game passes)

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

```go
ADMIN_PASS_ID :: "prod_admin";

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

{% hint style="info" %}
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).
{% endhint %}

### Reading product info (name/price/icon)

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

```go
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:

```go
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)

```go
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](https://docs.allout.game/monetization/in-game-products.md) (“Purchase Handlers / Grant Failures”)
* [Editing/Viewing Player Data](https://docs.allout.game/data-and-persistence/editing-viewing-player-data.md) (“Purchases” section)

### Testing purchases

In a game launched from the editor (Start Game or `run_tests`), `Purchasing.prompt_purchase` opens a test purchase prompt marked "Test purchase: no Sparks spent". It offers **Buy** whatever your Spark balance. Buy runs your `ao_purchase_handler` through the same server path as a real purchase, and a granted game pass then passes `Purchasing.owns_product`.

* The product must already exist for your game (see [In Game Products](https://docs.allout.game/monetization/in-game-products.md)).
* The prompt says "Purchase Complete" even when your handler returns `false`, so check the grant itself.
* Test purchases leave no purchase record. After the player rejoins, `owns_product` is false again and a failed grant is not retried. Anything your handler saved itself, such as currency, stays.
* Calling `ao_purchase_handler` yourself, for example from a chat command, runs only your grant code. It skips the server path and never sets `owns_product`.

In a test, press the prompt's buttons by name:

```go
test_buy_coin_pack :: proc() {
    Test.click_button("coin_pack_button");    // your UI that calls Purchasing.prompt_purchase
    Test.click_button("purchase modal/Buy");  // waits up to ~3s for the product to load
    Test.wait_seconds(3);                     // the handler runs 1-2s after Buy
    Test.click_button("purchase modal/Okay"); // closes "Purchase Complete"
    Test.assert_balance("coin pack granted", "Coins", 500);
}
```

### Cross-game (hub + minigames)

If you use game parenting, purchases can be shared across your games. See [Cross-Game Products/Data](https://docs.allout.game/data-and-persistence/cross-game-products-data.md).
