GameMaker Studio · GML · Currency & store

gmda_purchase

Spends in-game currency to buy a shop item by SKU (the server validates the balance).

Asynchronous (result via event)

Signature

gmda_purchase(sku, [idempotency_key]) -> real

What it does

POSTs /currency/purchase with the session headers. The server checks the balance and deducts atomically, applying the item's grant rules; the queued purchase_completed event carries success and response (the RPC payload, including the new balances). When success is false, response (or the event's error field) explains why, for example insufficient_funds, already_owned or item_not_found. Returns 1 once dispatched, or 0 when there is no active session.

Parameters

Name	Type	Default	Description
sku	string	required	The item SKU configured in the panel.
idempotency_key	string	optional	Optional key to make retries safe so the player is never charged twice. Omit it and the client generates a 24-character key for you.

How to call it

Call gmda_purchase(sku), then read the purchase_completed event with gmda_pollEvent(). Pass your own idempotency_key if you retry the same purchase so it is charged at most once.

Result event: purchase_completed { success, response }

Example

gmda_purchase("sword_skin");

// in the Step event, drain the queue:
var e = gmda_pollEvent();
while (!is_undefined(e)) {
    if (e.event == "purchase_completed") {
        if (e.success) show_debug_message("bought it");
        else show_debug_message("purchase failed");
    }
    e = gmda_pollEvent();
}

Use cases

Buy a cosmetic with soft currency.
Spend coins or gems on a power-up or unlock.

Functions Reference