Store

Beta

The store module is currently in beta. This is an invite only feature. If you are interested in using it, please get in touch with us.

The store module offers a simplified way to sell in-game items. It can work alongside your existing Xsolla integration. Using the buyItem method is required in order to enable in-app purchases on the CrazyGames mobile app. The method is also supported on the web.

Getting started

HTML5UnityGameMakerConstructGodotCocos

The module can be accessed like this:

window.CrazyGames.SDK.store;

The module can be accessed like this:

CrazySDK.Store;

Consult the Demo

For a demo, please consult the CrazySDK/Demo/StoreModule scene. You can run it directly in the Unity editor.

🟥 Not supported by the GameMaker SDK.

🟥 Not supported by the Construct SDK.

🟥 Not supported by the Godot SDK.

🟥 Not supported by the Cocos SDK.

Listing the catalog

HTML5UnityGameMakerConstructGodotCocos

Call listCatalogItems to read the virtual items configured in your Xsolla project.

try {
    const page = await window.CrazyGames.SDK.store.listCatalogItems();
    console.log("Catalog items", page);
} catch (e) {
    console.log("Catalog error", e);
}

Prices are per user

Xsolla personalizes prices and promotions per user, so the prices you get for a signed in player can differ from the ones a signed out player sees. Always display the prices returned by listCatalogItems rather than cached or hard-coded ones, so that what you show matches what buyItem charges.

Pagination

The method accepts an optional limit and offset, and returns at most 50 items per call, which is Xsolla's own maximum.

limit - how many items to return, a whole number between 1 and 50. Defaults to 50
offset - how many items to skip, a whole number of 0 or more. Defaults to 0

const page = await window.CrazyGames.SDK.store.listCatalogItems({ limit: 10, offset: 10 });

Errors

The listCatalogItems method rejects with a StoreError, for example:

{
    "code": "catalogFetchFailed",
    "message": "Could not reach the Xsolla store API."
}

Possible error codes:

invalidArgument - the limit or offset you passed is not a whole number in the allowed range
catalogFetchFailed - the catalog could not be retrieved from Xsolla (for example a network issue, or an invalid response)
unexpectedError - an unexpected error occurred
other

🟥 Not supported by the Unity SDK.

🟥 Not supported by the GameMaker SDK.

🟥 Not supported by the Construct SDK.

🟥 Not supported by the Godot SDK.

🟥 Not supported by the Cocos SDK.

Buying an item

HTML5UnityGameMakerConstructGodotCocos

Call buyItem with the item ID configured in your Xsolla project. The method opens the Xsolla Pay Station widget and resolves once the purchase is completed. Only one purchase can be in progress at a time.

try {
    const result = await window.CrazyGames.SDK.store.buyItem("your_item_id");
    console.log("Purchase completed", result); // { itemId: "your_item_id" }
    // the item can now be found in the Xsolla inventory
} catch (e) {
    console.log("Purchase error", e);
}

Warning

A successful buyItem call means the payment flow completed, but you should always confirm ownership on your back-end (or via the Xsolla inventory API) before granting valuable items. Never rely solely on the client-side result to unlock content.

Errors

The buyItem method rejects with a StoreError, for example:

{
    "code": "purchaseCancelled",
    "message": "The purchase was cancelled."
}

Possible error codes:

userNotAuthenticated - the user must be signed in to make a purchase
purchaseInitFailed - something went wrong while initiating the purchase with Xsolla
purchaseInProgress - a purchase is already in progress, wait for it to finish before starting a new one
purchaseCancelled - the user closed the payment widget without completing the purchase
unexpectedError - an unexpected error occurred (for example a network issue, or the payment widget failed to load)
other

Call BuyItem with the item ID configured in your Xsolla project. The method opens the Xsolla Pay Station widget and invokes the callback once the purchase is completed. Only one purchase can be in progress at a time.

CrazySDK.Store.BuyItem(
    "your_item_id",
    (error, result) =>
    {
        if (error != null)
        {
            Debug.LogError("Purchase error: " + error);
            return;
        }
        Debug.Log("Purchase completed: " + result);
        // the item can now be found in the Xsolla inventory
    }
);
// or
try
{
    var result = await CrazySDK.Store.BuyItemAsync("your_item_id");
    Debug.Log("Purchase completed: " + result);
}
catch (SdkError e)
{
    Debug.LogError("Purchase error (async): " + e);
}

Warning

A successful BuyItem call means the payment flow completed, but you should always confirm ownership on your back-end (or via the Xsolla inventory API) before granting valuable items. Never rely solely on the client-side result to unlock content.

Errors

The callback receives an SdkError as the first parameter (it is null when the purchase succeeds). The async version throws the SdkError instead.

Possible error codes:

userNotAuthenticated - the user must be signed in to make a purchase
purchaseInitFailed - something went wrong while initiating the purchase with Xsolla
purchaseInProgress - a purchase is already in progress, wait for it to finish before starting a new one
purchaseCancelled - the user closed the payment widget without completing the purchase
unexpectedError - an unexpected error occurred (for example a network issue, or the payment widget failed to load)
other

🟥 Not supported by the GameMaker SDK.

🟥 Not supported by the Construct SDK.

🟥 Not supported by the Godot SDK.

🟥 Not supported by the Cocos SDK.

Sandbox mode

HTML5UnityGameMakerConstructGodotCocos

While developing, enable sandbox mode so purchases run against Xsolla's test environment, allowing you to buy items with fake money.

window.CrazyGames.SDK.store.setSandbox(true);

While developing, enable sandbox mode so purchases run against Xsolla's test environment, allowing you to buy items with fake money.

CrazySDK.Store.SetSandbox(true);

🟥 Not supported by the GameMaker SDK.

🟥 Not supported by the Construct SDK.

🟥 Not supported by the Godot SDK.

🟥 Not supported by the Cocos SDK.

Local Testing

HTML5UnityGameMakerConstructGodotCocos

When the SDK is in the local environment (on 127.0.0.1 or localhost), buyItem always simulates a successful purchase, listCatalogItems returns a fake catalog of three items (a regular one, a discounted one and a free one, honoring limit and offset), and setSandbox only logs the new value.

When you are running the game in the editor, BuyItem returns a hard-coded response and SetSandbox only logs the new value.

You can customize the response returned by BuyItem with the Buy Item Response field in the CrazySDK/Resources/CrazyGamesSettings object. The available values are:

Success - returns a successful PurchaseResult for the requested item ID
PurchaseCancelled - returns the purchaseCancelled error
UserLoggedOut - returns the userNotAuthenticated error
UnexpectedError - returns the unexpectedError error

🟥 Not supported by the GameMaker SDK.

🟥 Not supported by the Construct SDK.

🟥 Not supported by the Godot SDK.

🟥 Not supported by the Cocos SDK.