In-game Stores

PlaytoliaStore gives you the product catalog and the purchase flow. It syncs automatically after the player logs in.

Three identifiers, three jobs

Every product carries three identifiers. Confusion between these three identifiers is the most common cause of a product that is null:

Identifier	Who creates it	Looks like	Use it for
`Code`	You, when you create the product	`gold_500`	To address a product from game code. It is fixed at creation and identical on every platform.
`Id`	Playtolia, automatically	`9f2c1e6a-...` (UUID)	To pass a product to the SDK or to the backend. Do not hardcode it.
`Sku`	The platform store	`com.mygame.gold500`	The listing in the App Store or the Play Store. It has a meaning in that one store only.

If you hardcode a product identifier in your game, the correct identifier is the product code. You cannot change a code after the product is created. This makes the code safe in your build.

Fetching products

var allProducts = PlaytoliaStore.GetProducts();
var consumables = PlaytoliaStore.GetProductsByType(ProductType.Consumable);
var nonConsum   = PlaytoliaStore.GetProductsByType(ProductType.NonConsumable);
var subs        = PlaytoliaStore.GetProductsByType(ProductType.Subscription);
var results     = PlaytoliaStore.SearchProducts("Gold");

// By your own product code, the usual case
var product = PlaytoliaStore.GetProductByCode("gold_500");

// By the Playtolia UUID, when you already have one in hand
var byId    = PlaytoliaStore.GetProductById("9f2c1e6a-4b8d-4d1f-9c3a-7e5b2a0d6f14");

// By the platform store SKU
var bySku   = PlaytoliaStore.GetProductBySku("com.mygame.gold500");

Product fields

Id, Code, Name, Description, Sku, Type (Consumable/NonConsumable/Subscription), Grants[] Each Grant has: GrantId, GrantType, GrantAmount, Currency?

Making a purchase

PlaytoliaStore.BeginPurchaseFlowByCode("gold_500",
    onSuccess: (receipt) =>
    {
        Debug.Log($"Purchase succeeded! Transaction: {receipt.ReceiptId}");
        Debug.Log($"Store: {receipt.Store}");
        Debug.Log($"Product: {receipt.Item.Name} ({receipt.Item.Code})");
    },
    onError: (error) =>
    {
        Debug.LogError($"Purchase failed [{error.Code}]: {error.Message}");

        if (error.Code == "USER_CANCELLED")
        {
            // User backed out, no action needed
            return;
        }

        if (error.Stage == "ACKNOWLEDGEMENT")
        {
            // Player was charged, SDK will retry automatically
            ShowMessage("Your purchase is being processed.");
            return;
        }

        ShowMessage("Purchase failed: " + error.Message);
    }
);

// Also accepts a Product directly, or a Playtolia product ID
var product = PlaytoliaStore.GetProductByCode("gold_500");
PlaytoliaStore.BeginPurchaseFlow(product,
    onSuccess: (receipt) => { /* grant confirmed */ },
    onError: (error) => { /* handle error */ }
);

CAUTION: BeginPurchaseFlow(string, ...) takes the Playtolia product ID, not the product code. If the value is one that you typed yourself, use BeginPurchaseFlowByCode instead.

The onSuccess callback receives a PurchaseReceipt with the transaction ID, the store, and the purchased product. The onError callback receives a PurchaseError with a machine-readable error code, a stage, and a message. Both callbacks are optional. When the purchase is successful, the SDK updates the wallet, the entitlements, and the subscriptions of the player automatically.

PurchaseReceipt

Field	Type	Description
`Item`	`Product`	The purchased product
`ReceiptId`	`string`	Platform transaction ID
`Store`	`string`	`"google_play"` or `"apple_app_store"`

PurchaseError

Field	Type	Description
`Code`	`string`	Machine-readable error code
`Message`	`string`	Human-readable description
`Stage`	`string`	`PURCHASE`, `VERIFICATION`, or `ACKNOWLEDGEMENT`
`ReceiptId`	`string?`	Set when the platform purchase is successful
`ItemId`	`string?`	Playtolia product ID (UUID)
`ItemCode`	`string?`	Your product code
`ItemSku`	`string?`	Platform SKU

Error codes

Code	Stage	When
`BILLING_UNAVAILABLE`	`PURCHASE`	The platform billing is not available on the device
`ITEM_NOT_FOUND`	`PURCHASE`	The catalog does not contain the product ID or the product code
`USER_CANCELLED`	`PURCHASE`	The user closed the purchase dialog
`PURCHASE_FAILED`	`PURCHASE`	The platform billing gave an error
`VERIFICATION_FAILED`	`VERIFICATION`	The backend verification failed
`ACKNOWLEDGEMENT_FAILED`	`ACKNOWLEDGEMENT`	The platform acknowledgement failed after the verification

CAUTION: The store data is empty until the player signs in. Before login, all product getters return null or an empty list.

When Stage is ACKNOWLEDGEMENT, the platform charged the user, but the acknowledgement failed. The SDK retries automatically at the next app start. A message such as “Your purchase is being processed.” keeps the player informed.

Listening to changes

void Start()    => PlaytoliaStore.AddListener(OnStoreChanged);
void OnDestroy() => PlaytoliaStore.RemoveListener(OnStoreChanged);

Wallets

Track currency after purchases

Entitlements

Track non-consumable unlocks

Get Started

Features

Billing

Advanced

Three identifiers, three jobs

Fetching products

Product fields

Making a purchase

PurchaseReceipt

PurchaseError

Error codes

Listening to changes

Wallets

Entitlements

​Three identifiers, three jobs

​Fetching products

​Product fields

​Making a purchase

​PurchaseReceipt

​PurchaseError

​Error codes

​Listening to changes

Wallets

Entitlements

Three identifiers, three jobs

Fetching products

Product fields

Making a purchase

PurchaseReceipt

PurchaseError

Error codes

Listening to changes